In an earlier post, Characteristics of Effective Technical Content, we listed predictability as being one of the characteristics of effective technical content.
Consistency is the key to predictability.
In today’s globalised world, organizations could have multiple technical writers working different pieces of documentation. However, at the end of the day, the documentation must have a consistent style and seem like it has been written by the same person. This requires all technical writers to follow a common writing style.
In addition, organisations use a variety of channels and media of communicate with the end users. Each medium or channel has its own list of dos and don’ts. As a technical writer—especially if on who is new to the team—it can be difficult to remember what to do and what not to do.
- the standard sentence constructs to use for certain actions. For example, Click <Button Name>. Or From the <UI Label> list, select XYZ.
- the preferred terminology for various things or actions. For example, select and clear are the verbs to use with a checkbox.
- the formal way to refer to various products and technologies. For example, Always write the product name as Company Name® Product Name™ when it is the first time in a chapter, and as Product Name™ thereafter.
- grammar and punctuation rules. For example, Use the serial or Oxford comma after all list items except the last. Or Use the present tense.
- what not to do. For example, Do use the first person.
- how to write and format headings, part names, UI labels, etc. For example, Use title case for headings. Or Write UI labels in bold.
- the kinds of images you can use in a document and the formats of the images. For example, Images should have a resolution of 300 DPI and be saved in the PNG format.
- the layout to be used for various outputs.
- and much, much more…
Take a look at Microsoft’s Wiki: User Experience Guidelines
When a style guide is available, it becomes a ready reference for the technical writers and helps them help themselves.
Apart from helping maintain consistency, a well-written style guide can help in reducing:
- training time
- review time
- costs associated with running a technical writing team
So be consistent; use a style guide!