Re: spec writing - is simple ever wrong ?

[Chris Morton <salt -dot- morton -at- gmail -dot- com>]

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/rfc-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 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