TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I have had similar problems over the years with fake legalese. When pushed to explain their case, people who put it in docs often think it sounds more 'professional'. It doesn't. They have not thought their logic through. Hopefully they see this when I say, we *are* professionals and we show we are professionals when we say exactly what we mean (as systems professionals) in language most easily understood by our readers, and leave the legal words for lawyers.
Cheers, Diana
-----Original Message-----
From: techwr-l-bounces+diana -dot- corrigan=visionsoftware -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+diana -dot- corrigan=visionsoftware -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Chris Morton
Sent: Wednesday, 31 July 2013 11:13 a.m.
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: spec writing - is simple ever wrong ?
I think we flushed this all out many months ago when I objected to the use of "shall" in these docs, e.g., "The frabulator shall frabulate."
It appears that much of what we wrangle is a holdover of gubmint spec work, with an abundance of parties apparently being insistent on promoting such stilted language in perpetuity.
> Chris
On Tue, Jul 30, 2013 at 3:39 PM, Monique Semp <monique -dot- semp -at- earthlink -dot- net>wrote:
> Hello, WR-L-ers,
>
> I'm editing a specification, and I was merrily redlining all sorts of
> convoluted wording to be simple and straight-forward. But then I
> thought, perhaps there's a reason that so many specs are so awkward to
> read. Maybe there is some spec writing requirement, beyond the usual
> SHOULD, MUST NOT, etc. definitions, that in effect requires
> indirectness? After all, why else would so many specs be so difficult to make out?
>
> For example, why should a spec say "in the case of" instead of "if"?
> Why should "moreover" be used so much more often than "and",
> especially when both could be omitted altogether?
>
> Any thoughts?
>
> For reference:
>
> * I did find the RFC Document Style Manual,
>http://web.archive.org/web/20090418061257/http://www.rfc-editor.org/rf
> c-style-guide/rfc-style-manual-08.txt,
> but it certainly doesn't say to be excessively wordy!
>
> * Not really related, but interesting, is this thread about
> programming language specifications:
>http://programmers.stackexchange.com/questions/23542/how-do-i-go-about-writing-a-programming-language-specification.
> I haven't digested it fully yet, but it doesn't seem to be concerned
> with natural (vs. programming) language issues.
>
> -Monique
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> New! Doc-to-Help 2013 features the industry's first HTML5 editor for
> authoring.
>
> Learn more: http://bit.ly/ZeOZeQ
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as salt -dot- morton -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>http://www.techwhirl.com/email-discussion-groups/ for more resources
> and info.
>
> Looking for articles on Technical Communications? Head over to our
> online magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our
> public email archives @ http://techwr-l.com/archives
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
