RE: spec writing - is simple ever wrong ?

Subject: RE: spec writing - is simple ever wrong ?
From: Diana Corrigan <Diana -dot- Corrigan -at- visionsoftware -dot- com>
To: "salt -dot- morton -at- gmail -dot- com" <salt -dot- morton -at- gmail -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 30 Jul 2013 23:32:38 +0000

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.

Learn more: http://bit.ly/ZeOZeQ

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as Diana -dot- Corrigan -at- visionsoftware -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.

Learn more: http://bit.ly/ZeOZeQ

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -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


Follow-Ups:

References:
spec writing - is simple ever wrong ?: From: Monique Semp
Re: spec writing - is simple ever wrong ?: From: Chris Morton

Previous by Author: documenting iPad app
Next by Author: Re: SharePoint question
Previous by Thread: Re: spec writing - is simple ever wrong ?
Next by Thread: Re: spec writing - is simple ever wrong ?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads