Re: spec writing - is simple ever wrong ?

Subject: Re: spec writing - is simple ever wrong ?
From: David Farbey <dfarbey -at- yahoo -dot- co -dot- uk>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 6 Aug 2013 09:12:40 +0100

Engineers (of any discipline) are taught to write a specification so the
fabricators know what to build, and so that the quality assurance people
know what to test for. So the specification quite rightly says "the beam
shall support objects up to 250kg", the fabricators build a beam that
supports 250kg, and the quality assurance team load the beam with weights
until it breaks, hopefully at no less than 251kg.

Once the product has been built and has successfully passed all its tests,
no-one needs to see the spec again. But then someone suddenly remembers
that they need some sort of user guide for customers (or in Chris's case,
they suddenly remember they need a set of SOPs for internal staff), and
they recycle the spec document. And that becomes the company standard.

[Enter, stage right, the eager tech writer who earnestly believes that user
guides should help users do their jobs. For what happens next, see multiple
threads in this list going back years and years.]

David

David Farbey - david -at- farbey -dot- co -dot- uk
Mobile 07538 420 800
http://about.me/davidfarbey



On 31 July 2013 14:55, Erika Yanovich <ERIKA_y -at- rad -dot- com> wrote:

> 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 dfarbey -at- yahoo -dot- co -dot- uk -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:

Previous by Author: RE: Is there any way to create links from a graphic to topics in CMS
Next by Author: Re: Punctuation in quotes -- American style
Previous by Thread: TECHWR-L Premium Jobs, Events, and Announcements
Next by Thread: Re: spec writing - is simple ever wrong ?


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

Sponsored Ads


Sponsored Ads