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
As a technical writer you are supposed to tell your readers what to do and how to accomplish specific tasks. It would not be an exaggeration to say that your task, in essence, is to show them “how the world works and how to act correctly when the situation demands it.”
When that is your mission, you’d better do it with authority and clarity. That’s your responsibility as a professional communicator.
Prevarication, equivocation and “hedging your bets” might be a good tactic in politics and diplomacy so that there is always room for “plausible deniability.” But in technical writing you should have no room for such uncertainty.
When you describe a process, your sentences should have only and only one meaning. Otherwise you could do great harm, even when not intended.
Imagine your “Nuclear Plant Maintenance and Troubleshooting Manual” has a step that reads like this:
“When the temperature rises precipitously you may try closing Valves A or B and shut down Module C or D” …
I guarantee you, that would lead to a disaster because such a description leaves so much to the imagination and personal choice of the operator.
What does “precipitously” mean exactly? Does it mean “20 F degrees in 30 seconds” or “120 C degrees in 7 seconds”?
Does “may try” mean the operator is also at a liberty “not to try”? And what does it mean to “try” anyways?
Valve A or B? Module C or D? Is there a difference between them or not? What if the operator decides to close down both?
A better description would read like this:
“When the temperature rises 120 C [Celsius] in 7 seconds, follow these steps IMMEDIATELY:
1) Close Valve A by turning it clockwise until you hear three consecutive clicks.
2) After making sure Valve A is closed, shut down Module D by pulling Switch Z down from ON to OFF position.”