RE: spec writing - is simple ever wrong ?

Subject: RE: spec writing - is simple ever wrong ?
From: Erika Yanovich <ERIKA_y -at- rad -dot- com>
To: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 31 Jul 2013 13:55:50 +0000

Excellent point. When my employer needs to send specs (or other internal docs) to customers, we edit them. Otherwise, we let them be in their "internal" language.
Erika

-----Original Message-----

The first question that comes to my mind is, why are you editing a spec, anyway?  In the first sense of the question, my instinct is to question the value of the exercise.  What's important in a spec is that it covers the full range of events, inputs, outputs, etc.  Who cares if the language is optimal, so long as a reasonable person can recognize the necessary information?  For example, I worked with a Japanese engineer in the US, helping him express his spec in readable English. I would say that was meaningful because nobody could understand his writing without that help. 


The second sense of the question is probably more useful -- who is going to benefit from your edits?  That should be able to guide your decisions.  Of course, you must always make sure you don't change the meaning of any statement.  And (moreover?) you will probably find statements where the precise meaning isn't clear.  In such a case you are adding value (see paragraph above).  But it isn't necessary to replace every "moreover" with an "and", etc.  Only the instances where "moreover" should be "instead of" (for example).  In other words, if, in spite of the convoluted and tortured language, a statement can be parsed to mean only one thing, and that one thing is the author's intent, don't mess with it.  That's my instinctive reaction.


As to why the writing is like that...  I suspect university writing is the culprit.  These gals and guys wrote like this to get out of school, and they naturally write like this to get past the dreaded specification stage.  Maybe instead of editing specs you could host some brown-bag lunches to teach simpler, quicker, more effective writing. 


As my father always used to say, eschew obfuscation.


cud


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


References:
Re: spec writing - is simple ever wrong ?: From: Chris Despopoulos

Previous by Author: RE: Taking active vs. passive voice too far
Next by Author: RE: How can I phrase this?
Previous by Thread: Re: spec writing - is simple ever wrong ?
Next by Thread: OT: Wise sayings (was spec writing)


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

Sponsored Ads


Sponsored Ads