Latest posts by techwriter (see all)
- How to Count the Number of Days with an Incident and Chart with Running Averages in MS Excel - October 19, 2016
- FREE Online Video Course – MS Word Power Shortcuts - October 14, 2016
- INFOGRAPHICS – Which Business Entity is Right for You? - September 28, 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.