spec writing - is simple ever wrong ?

Subject: spec writing - is simple ever wrong ?
From: "Monique Semp" <monique -dot- semp -at- earthlink -dot- net>
To: "TechWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 30 Jul 2013 15:39:51 -0700

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 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:

Previous by Author: "mock", not "mock-up", as a noun ?
Next by Author: Re: Framemaker 9 working environment
Previous by Thread: Re: "mock", not "mock-up", as a noun ?
Next by Thread: Re: spec writing - is simple ever wrong ?


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


Sponsored Ads