TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.]
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.
