Re: spec writing - is simple ever wrong ?

Subject: Re: spec writing - is simple ever wrong ?
From: Chris Morton <salt -dot- morton -at- gmail -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Tue, 6 Aug 2013 07:01:24 -0700

Well stated, Mr. F. > Chris

On Tue, Aug 6, 2013 at 1:12 AM, David Farbey <dfarbey -at- yahoo -dot- co -dot- uk> wrote:

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


References:
Re: spec writing - is simple ever wrong ?: From: David Farbey

Previous by Author: Re: Structured FrameMaker Master Pages
Next by Author: RE: Punctuation in quotes -- American style
Previous by Thread: Re: spec writing - is simple ever wrong ?
Next by Thread: New Massachusetts Computer/Software Tax


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

Sponsored Ads


Sponsored Ads