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