One common complaint, and one to which I have fallen prey in the past, is that “no one reads the documentation”. This seems to be a particular problem for documents recording process and procedure. In this series we will look at how you can write documents that people will actually read.

We will look at every aspect of documentation, including each of the following.

• Audience — Who are you writing for? And, how to make sure your document appeals to them.
• Content — What are you writing about?
• Structure — Creating documents that make finding information easy.
• Presentation — Creating documents that are appealing.
• Delivery — The different methods of delivering information.

Many documents focus only on content, neglecting all other aspects. This is in part because many documents are written to the same formula by domain experts. They are not written to be read, they are written to comply with a requirement that they exist.

This series is not interested in producing documents for compliance, it is interested in producing documents that are useful and used.

Audience

When you write anything you must have an audience in mind. When writing this, for example, I have in mind people like myself; people called upon to write documents describing policies, plans, processes and procedures. In particular I imagine someone who has documented processes and procedures in the past but has been disappointed that their documents are not read or referred to by the people for whom they were written.

Why do people not read these documents?  To answer this question I would like to turn it around. Why do people read? What motivates people to read anything?

People read for two main reasons.

• Pleasure
• Acquisition of knowledge

It is unlikely that anyone will read process documentation for pleasure, but this does not mean process documents should be unpleasant to read. In later posts we will look at making documentation more appealing to read.

Most people will read process documentation for one of the following reasons.

• They must follow the process to achieve some goal.
• They need to be reminded of a process, required to achieve some goal.
• They need to verify that a process has been followed, in achieving some goal.

The common thread being ‘to achieve some goal’. The important take-away lesson for this section is that your audience is reading these documents in order to achieve some other goal. Technical documentation is not read for pleasure but for purpose. The reading of the document is a means to an end, not an end in itself.

The first step in writing effective documentation is knowing what your audience wants. What goals are they trying to achieve by reading your document? Answering this question will inform all other aspects of the writing process.

Knowing what question your document must answer for your audience is a big step toward writing a good document that will be read. Another important feature is knowing how your audience reads. By this I mean, knowing whether your audience is technical or not, do they understand a certain type of jargon? In short, you must know what sort of language to use in your document to make it as concise, intelligible and appealing to your target audience.

It is pointless writing a heavy technical document (that may be accurate and achieve the intended goal of you audience) when your audience has no technical inclination. They simply will not understand it, or at best they will have to work very hard to understand it – in which case they will not read it.

Identifying your audience

This is usually the easiest part of the writing process. Imagine who will use your document.

Most organisations have some form of review process. Unfortunately these reviews are too often performed by the wrong people and this leads to poor documents being produced. Too often documents are written for the reviewers and not for the users.

Suppose you are tasked with writing the build management process document for a large project. The review will include the project manager. You may end up writing a document for the project manager, but this is not the audience that will actually use the document. The only time that the project manager will ever see the document is in the review. The principal audience for the build management process document are the developers and build managers. You should be writing for this audience.

The project manager is important in approving the process, not in approving the document. This is a very important distinction. Once the process is agreed the project manager should only be involved in confirming that the document accurately records the process. They should have no other input into the document (unless they are also a developer, build manager, or other legitimate audience member).

Bottom line – write for the user, not the reviewers.

Next time I will look at selecting content.