How to Create Good User Documentation

Step 1 - Assess the purpose of the documentation

Begin the documentation process by assessing the purpose of the document. Different documents serve different purposes. For example user guides inform a products users how to best use a product and get the most from it, while a sales presentation's purpose is to get the reader to buy a product. It is important to establish what you want the document to achieve, as this will influence the rest of the documentation process.

Step 2 - Assess what tasks the users will perform

This step involves assessing the tasks users will perform, this is known as a task oriented approach. The task oriented approach begins by focusing on how the users would use the software or product to solve their problems or complete real world tasks.

The task-oriented approach creates more useful documentation than the functional approach to document development, which involves describing each button and function. The problem, with the functional approach is that it only gives the user half the story and does not help to integrate the software or product with real world tasks that the user will need to perform. This can often leave users with a low opinion of the software or product, when it was really the documentation that let them down.

At the end of this stage you will have a list of tasks and sub-tasks that will provide a skeleton for the documentation.

Step 3 - Analyse the audience

The audience analysis is where you create a profile that provides generic information and any assumptions you are making about the different audiences groups the document will have. Working from the audience analysis helps you to tailor the documentation as closely as possible to the needs of the reader. The audience analysis is where you try to understand who will be using the product you are documenting and what assumptions you can make about the knowledge and skills they possess. This allows you to include the appropriate level of detail and write using language that each audience group will understand.

Step 4 - Develop an audience task matrix

The audience task matrix links the tasks to the different audiences that a document is likely to have. The audience task matrix provides a useful tool for structuring the documentation, grouping information by likely audience and if required, helping us split a document that was too large. It also provides an additional check that all users and tasks have been considered.

Step 5 - Create the document plans

The next step is to create the document plans based of the information from the previous steps. This is a top down process, which you start by creating a high-level table of contents. Then you loop between the document plan and information gathering until you feel you have all the required content for each section.

Step 6 - Gather information

The information gathering process involves a combination of interviewing Subject Matter Experts (SMEs) and working from existing documentation. For example, when documenting software there is often valuable information in requirement specifications, functional specifications and use case documentation. This provides a basic level of information that you can build on through interviewing the SMEs.

Step 7 - Design the look and feel of the document

Designing the look and feel of the document involves deciding what format to use. For many projects a paper document may not be the best choice, an online help system or a web page may provide a better solution. It is important that the document looks good and is easy to read, so you need to consider the page layout, use of white space and visual density. You also need to take into account navigation features, so that multiple users can navigate through the document in different ways. At this stage you must also check if there are corporate guidelines or style guides that the document needs to adhere to.

Step 8 - Begin the writing process

Now you have a good idea of the content and a template to work with you can begin the writing process. During the writing process you focus on presenting information consistently, separating procedural information and reference material, determine the most effective use of images and diagrams, and making sure the information is tailored to the appropriate audience.

Step 9 - Edit and proofread the documentation

Finally you edit and proofread the documentation. You check each document against a proofreading checklist. If there is a style guide for the documentation then base the checklist on the style guide. This is an iterative process where the sentence structure and clarity of the document improves with each pass.

Buy Research Papers
Sample Dissertations