0Tip 1) Quit it with the Passive Voice
The passive voice is a plague on effective documentation. It reduces its clarity, its consistency, and the efficiency and tightness of the writing. The passive voice is writing in which the subject of the sentence denotes the recipient of the action rather than the performer. For example, “the server was installed” represents the passive voice while “the technician installed the server” represents the active voice. The passive voice is more common in most documentation because it is an easier, sloppier way of writing.
Writing in the passive voice is highly detrimental to documentation, especially to process related documentation where it is essential to understand which people or systems are performing the actions. The good news is that this is an easy fix. Under your Grammar function in Word, you can click on the “Passive Sentences” option and Word will automatically check for passive sentences for you.
To improve your documentation immediately: Use the Passive Voice grammar check function in Word to review your documentation and to change passive sentences into clearer, sharper active sentences.
Tip 2) Use Simple Visuals to Engage your Reader
You might not be a graphic artist, but you can improve your documentation quickly through using simple visuals. Take advantage of the many canned Shapes and Smart Art in Word to add a little “punch” to your documentation to better engage your audience.
If you have Microsoft Visio, then take advantage of the many ways that this program offers to draw simple diagrams which reduce your need for extensive text and which improve your chances of stakeholder engagement. One diagram that is particularly useful is the swim lane diagram which illustrates actors and their actions. Without being a process expert, you will be surprised how the simple Swim Lane will improve clarity in roles, responsibilities, and processes for your team and your organization overall.
To improve your documentation immediately: Create visuals in your documentation to illustrate your key messages, replace blocks of text, and to hold your readers’ attention.
Tip 3) Use Great Titles and Bullets
Remember, your audience generally wants to exert as little as energy as possible when reading your work. They’ll just “skim” your document looking for the main points. So, make things easy for them! Headers and bullets, often combined with effective visuals, are as important as the text. For some readers, headers and bullets are all that they will read. Your reader might even make a decision about your work just by reading the table of contents. So, when assessing your documentation, it’s helpful if the entire gist of your work is communicated by the headers and bullets alone. Does the reader understand what you are trying to say? If they can understand most of what you are saying just by reading the headers, then you have done a good job.
To improve your documentation immediately: Revise your headers and bullets to summarize the whole document.
Tip 4) Tame your Acronyms and Buzz Words
There is perhaps nothing more annoying when it comes to documentation than walking onto a project or into a new organization and to be unable to understand a single paragraph in the document, because it is so full of acronyms and buzz words. Acronyms and buzz words do not, let me repeat, make you sound smarter. In most cases, they actually annoy your reader through hindering her ability to grasp your key messages.
Avoid using excessive acronyms and buzz words whenever possible. Or at least, define them upfront. In many cases, you should define acronyms and frequently used words in a well thought-out Glossary at the beginning of your documents or as part of your documentation library.
To improve your documentation immediately: Learn to tame your use of excessive acronyms and buzz words. If you need to use them, then make sure that you define them upfront at the beginning of your documents or documentation library.
Tip 5) Use the Reperformance Standard
One of the key challenges that organizations face in developing and maintaining excellent documentation is that they do not have a consistent standard for assessing their documentation. In reality, there are many different types of and uses for documentation and using one consistent standard is difficult. There is however one standard that provides a strong metric for most documentation. This standard is called the “reperformance standard”.
The reperformance standard states that the documentation must enable a user to “reperform” the related task or process. That is, the documentation must have sufficient detail and communicate with enough clarity through its text or visuals as a standalone document to allow the user to execute the steps. Although more commonly used by assurance and audit professionals, the reperformance standard can be expanded to many other applications within organizations, including training materials, user manuals, process documentation, and disaster recovery documentation. So, test the quality of your documentation against this standard and challenge yourself to ensure that you are meeting it.
To improve your documentation immediately: Review your document and ask: can someone else reperform these tasks based on what is written here? If the answer is no – revise it so they can.
