Your documentation problems solved in 5 easy steps

By Ellis Pratt 24 July 2007

1. Identify the central question/subject.

It is important you know the key purpose of your document: Who is your audience? What do you want to happen as a result of someone reading it? Try to understand the user and see through their eyes. You can do this by pre-empting questions the readers may have:

• What do you want to tell me?
• Why should I read this?
• What do I need to know?
• What do you want me to do?
• Are you requesting, proposing or seeking approval?

2. Plan the structure of the document using labels to describe each section.

The pyramid style of writing, devised by Ron Blicq, is a very useful way of arranging the structure of your document:

• Start the document by writing "I want to tell you that...", finishing that sentence and then deleting the phrase "I want to tell you that..." This should help you communicate your key message in your first sentence.
• Start every section with a summary overview statement. This will encourage people to read on.
• Follow the summary statement with any supporting details that justify it.

3. Identify the best style of language.

Here is some advice regarding the words you use:

• Keep your vocabulary simple. This will aid your reader's understanding. For example, "use" is better than "utilise".
• Use the words and phrases your readers would normally use, where possible.
• Be consistent with the terminology you use.
• Check your document for any spelling mistakes.
• Use the active voice, as it will help make your writing seem much more definite and confident.
• Be succinct.
• Separate task (how) information from background (why) and support (what) information.
• When writing instructions: identify who should do what, what you should do before you start and what should happen next.

4. Write drafts and get them reviewed.

For longer documents, expect to write three drafts and be refining the structure as you go along.

During the first draft stage, the author writes the content for all the topics. This is the longest stage and takes the longest to review. The review is to check for technical accuracy of all the content. The second draft stage is for the author to make the necessary changes, reported from the first draft review. The review is to confirm that this has been done and to request any minor tweaks still outstanding. The final stage is to follow up on the minor changes picked up at second draft review. The result is the final deliverable.

You can look at a document a hundred times and still miss errors. Getting somebody to review your documents will benefit you by reducing errors and getting feedback on what your readers are likely to think about your information.

5. Identify the best delivery method.

It's not uncommon for 30% of a writer's time to be spent working on the "look and feel", once all the writing has been done. Of course, documents designed to be read on paper don't work when they are read on a screen, so it's important to change the formatting to suit the delivery medium. The more documents (and the content contained within them) are published in different places, the more important it will be for you to be able to create these without being faced with spending lots of time on reworking. Look at the tools you use, to see if you can control the "look and feel" independently of your content. You can achieve this partly by using standard templates, but you might want to consider using content management software.

Be consistent, as this is a real time saver. If you are using a word processor, you can format the headings with the preformatted styles contained in the word processor templates (For example "Heading 1" and "Heading 2" styles in Microsoft Word). A style within Microsoft Word is a set of formatting characteristics that you can apply to text in your document to quickly change its appearance. When you apply a style, you apply a whole group of formats in one simple task. Using styles makes it easier to make changes to the look and feel across the whole of the document, and makes it easier to import the content into other software at any stage in the future.

If you have more than one type of audience reading the document, don't be afraid to break information into separate documents. You could also provide a series of ways to navigate around the document (such as alternative tables of content, indexes and tags), suited to each particular audience.