Write Your Technical Documents with a Consistent Style Guideline

© 2010 Ugur Akinci
A consistent technical document is one that instills confidence and trust in end-users. It all starts with a template. It doesn’t matter whether you are creating a book, help file, or a web site. A template is a must.
Once you’ve got your template designed and under control, you need to follow a style guideline to create a well-rounded and consistent document.
Here are some useful pointers:
Start all your ordered (numbered) and unordered lists with an action verb.
“Enter your password” is better than “The system will ask you to enter your password. Please do so.”
A great many user actions in software documentation address a user clicking a button in order to display a certain screen. Follow the same pattern by using the same kind of compound sentence to describe those two related action.
For example: “Click the Next button to display the configuration screen.”
You can use the same first-this-followed-by-that pattern within a hardware context as well:
Another: “Measure the voltage before connecting the wires to ensure safety.”
Decide whether you want to use “check box” or “check-box” and stick with it. Don’t shift back and forth between those two usages.
Same goes with “dropdown box” and “drop-down box” or “drop-down list.”
Table captions usually precede the tables, whereas figure captions follow the figures. Make sure you are consistent with the way you use your table titles and figure captions as well.
There are no stylistic and absolute rights or wrongs in this business and there’s no such thing as “too much” consistency when it comes to technical writing. What’s more important is to make a set of style and format decisions and stick with it.