The Golden Rules of Good Documentation

Hopefully you are now set up to use Word efficiently and effectively, avoiding the pitfalls described in our companion article. This means you have a comprehensive and well-designed template and your team has been trained on how to use it. Now that you don’t have to worry about formatting and layout; you can concentrate on structure and content.  Here are our ‘golden rules’ of good documentation.

Golden Rule #1: Know your purpose and audience

Why is your document needed? Is it intended to inform, present options for decision, or set out process steps to be followed? How does it relate to other documents?

The first section you should write is an introduction covering the document’s background, purpose, scope and target audience. If you cannot clearly articulate those things then you are not in a position to write your document.

Golden Rule #2: Structure is everything

… or at least 75% of the battle. Badly structured documentation will only serve to confuse readers and will always detract from the message a document is trying to convey.

A structure should be logical and immediately evident to the reader. Use numbered headings and hierarchical fonts that clearly demonstrate descending heading levels. Never have more than three levels of heading; any document can be structured to meet that requirement. If your document has a section 3.2.5.1.4 then there is no possibility that your reader will understand your document’s messages.

‘Signposting’ should be used to lead the reader through the document. Signposting explains the document’s structure, and which topics are covered where, and why. This could include an overview of the whole document within the introduction section, and at the start of each main section, setting out the key elements of that section.

Appendices should be used to keep your document clear and concise. If detail is obscuring the key messages, syphon that detail into an appendix. This can also help to meet the needs of different audiences for greater or lesser detail.

Documentation structure can also be extended to cover a suite of related documents, but that is a topic in itself and will be revisited in a future article.

Golden Rule #3: Make the first draft as good as possible

This rule could be restated as ‘A document never recovers from a poor first draft’. This is because most reviewers will not be ruthless enough to completely scrap a bad document and start again when required. This means that even with extensive rewrites bad elements of the original draft may endure to the final version.

It is better to ensure the first draft is as good as possible to avoid these issues, which can only be achieved through rigorous, highly critical self-review.

Golden Rule #4: Be concise. But not so concise as to be ambiguous

Too much text will often obscure the key messages in a document, and so it is important to use as few words as possible to get across the key points. However, beware of introducing ambiguity through excessive conciseness: when in doubt, it is better to err on the side of too much than not enough, to ensure the meaning is clear.

Be wary of using the word ‘clearly’, as this is often used to avoid fully detailing a reasoning step or logical link. It is always better to fill in the skipped step even if it may seem obvious to an author who is fully familiar with the material.

Golden Rule #5: The Executive Summary stands alone

Any document over a handful of pages long should have an executive summary. This should be written last, when the rest of the document is in, or close to, its final form.

A good executive summary briefly covers all the main elements from the document: the purpose, what has been done, and the key conclusions. There should be nothing in the executive summary that does not appear in the main document. An executive summary is not an introduction, a guide to the structure of the document or a conclusions section. It should be possible for a reader to read only the executive summary and get a picture of the whole document, albeit at a high level.

Golden Rule #6: There is only one live version and everyone knows who has it

A single live document should be maintained, and it should be edited sequentially by different authors. Do not let authors edit simultaneously as this can lead to key edits being missed from the final version.

Ideally a check out system like SharePoint should be used but if this is not possible and folder sharing is being used then clear communication between authors and reviewers is key. Everyone should know who has the live version and should request ownership of the live version before making any changes to minimise the risk of branch versions – which are time consuming and difficult to merge accurately.

Hopefully our Golden Rules above coupled with your well-designed template from our previous article will set your team well on their way to creating clear, high quality documentation that is easy to maintain and update. Thanks again to our documentation guru John Bennett for helping us distil these principles. If you would like to speak to us regarding all things documentation, or on how APR can help elevate the quality of your documentation, please do get in touch.

James Nicholl

May 2021