Technical Writing – How to write a technical document consistently and maximize user confidence?

A coherent technical document is one that instills security and confidence in end users. It all starts with a template. It doesn’t matter if you’re creating a book, a help file, or a website. A template is a must.

Once you have designed and controlled your template, you must follow a style guide to create a complete and consistent document.

Here are some helpful tips:

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 large number of user actions in software documentation refer to a user clicking a button to display a certain screen. Follow the same pattern by using the same type of compound sentence to describe those two related actions.

For example: “Click the Next button to display the setup screen.”

You can also use the same first-this-followed-by-that pattern within a hardware context:

Other: “Please measure the voltage before connecting the wires to ensure safety.”

Decide if you want to use “checkbox” or “checkbox” and stick with it. Do not switch back and forth between those two uses.

The same goes for “drop down box” and “drop down box” or “drop down list”.

Table titles usually precede the tables, while figure titles follow the figures. Be sure to be consistent with how you use table titles and figure legends.

There are no absolute stylistic hits or misses in this business and there is no such thing as “too much” consistency when it comes to technical writing. What’s most important is making a number of style and format decisions and sticking with them.