Sharp Words

I’ve mentioned before (particularly in How to Write a How To) that when writing technical documentation, it’s important to keep a number of things about it as consistent as possible. In this post, I want to elaborate on some of the different areas in which consistency is important.

But first of all, why is consistency important? Well, it helps readers. It makes it easier for them to locate information in a document and locate, for example, menu items on the software interface.

It also helps writers and reviewers - writers don’t have to think about how many different ways they can describe the action of clicking the Open button, and reviewers don’t have to try and decide which way is better. Defining the terms and language to be used for consistency is important - most technical writers will have a style guide (or more than one) which contains this sort of information.

And it’s very important when localising documents. Consistent terms and language makes a translator’s job easier and cuts down on costs and time.

Consistency of terms
Always refer to bits of the software or hardware by consistent terms. Don’t call something a ‘drop-down list‘ in one part of the procedure and then refer to a similar bit of the user interface as a ‘combo box‘ later on.  If necessary, include a reference chapter or appendix with diagrams that show what you mean by all the bits - this would be very common in a manual for a physical object.

If the product you’re writing about has terms specific to its use and area of use, make sure you define these - preferably both in a glossary and when a reader might encounter the term for the first term.  For example, if part of product A deals with Woojits, then make sure you include woojit in the glossary and also explain what a woojit is in the introduction to the chapter or section about them.

Consistency of language
Keep your phrasing consistent throughout a document. For example, use either ‘From the File menu, select Save‘ or the alternative ‘Select Save from the File menu‘ throughout a procedure; don’t mix them.

Consistency of style
This might sound trivial, but always using the same formatting to indicate a button, for example with bold text, makes instructions easier for readers to follow, and makes items of interest stand out in the text.

And of course, using the same styles and formatting in all the guides for a particular company or product acts as a form of corporate branding.

Consistency of structure
If you have a set of guides related to the same product, or for different product but containing similar information, it makes sense to have a standard structure of chapters and appendixes. For example, all documents I produce for software applications would start with these chapters:

• Overview of the product (a general introduction to what the product is for)
• Installing the product
• Getting started with the product (how to get connected/logged in, a description of the interface)

Structural consistency between documents mostly makes it easier for readers to find information, and also makes using a content management system or content re-use system easier for writers!

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts