Latest posts by techwriter (see all)
- Test Your Knowledge of 4 Basic Fonts – Drag & Drop - January 27, 2017
- How NOT to Design a Web Site - January 25, 2017
- Hazards of Poorly Written Technical Documentation - December 26, 2016
© 2010 Ugur Akinci
Technical writing fails when it tries to become “fine writing” or “creative writing.”
Why? Because one of the main tools of “fine writing” is attributing human-like qualities to non-human actors and agents. That’s a definite taboo in technical documentation. (“Anthropomorphizing” is the $100-word that says the same thing.)
For example you commit that error every time you write a sentence like “When the system becomes aware of a user selection, it switches channels.”
“Awareness” is an attribute of organic (human, animal, or perhaps even plant) consciousness. Machines and computer systems are not “aware” of anything the way we humans are aware of things.
A better sentence would be: “When the system detects a user selection, it switches channels.” Here there is no claim that the “system” is “alive” with “consciousness.”
The same “fine writing” error is committed when a technical writer uses adjectives, superlatives, and draws an exaggerated picture of technical states and processes.
For example, in a novel, it may be commensurate with “poetic license” to talk about a “gorgeous pomegranate-colored red pilot light” turning on when the user pushes the OFF button. But in a technical document such an exaggerated description comes across a ridiculous.
A better description would be a “red pilot light is turned on when the user pushes the OFF button.” It’s simple, correct, and effective.
Again: “When you hear an awful sound coming from the B module, it’s time to change the oil.” The adjective “awful” does not belong in technical writing since it’s meaning is subjective and can change from one person to another. A technical document needs to be as objective as possible to eliminate any variation in application.
A better sentence would be: “When you hear a high-pitched sound coming from the B module, it’s time to change the oil.”
Of course, one can get really “anal-retentive” about it by defining the frequency and note of the sound in question and thus really nail the definition of “high-pitched” to the wall; but I’ll leave it at that since I’m sure you get the idea.