|
|
 |
|
|
How To Create Good User Documentation by Stephen Allen
|
|
|
How To Create Good User Documentation |
|
|
|
|
|
Education
|
|
|
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. writing service reviews
Related Articles -
Create, Good, User,
|
Rate This Article  |
|
|
|
|
|
Do you Agree or Disagree? Have a Comment? POST IT!
| Reader Opinions |
|
|
|
|
|
|
|
|
|
| Author Login |
|
|
 |
Advertiser Login
ADVERTISE HERE NOW!
Limited Time $60 Offer!
90 Days-1.5 Million Views
|
|
TIM FAY
After 60-plus years of living, I am just trying to pass down some of the information that I have lea...more
|
|
|
|
|
LAURA JEEVES
At LeadGenerators, we specialise in content-led Online Marketing Strategies for our clients in the t...more
|
|
|
|
|
ALEX BELSEY
I am the editor of QUAY Magazine, a B2B publication based in the South West of the UK. I am also the...more
|
|
|
|
|
STEPHEN BYE
Stephen Bye is a fiction writer. His most recent novels are a 5-book “The Developer” series which be...more
|
|
|
|
|
PAUL PHILIPS
For more articles, blog messages & videos and a free e-book download go to www.NewParadigm.ws your p...more
|
|
|
|
|
LEVAL AINAH
I am an internet marketer and also an educator. My goal is to help others who are looking to improve...more
|
|
|
|
|
GENE MYERS
Author of four books and two screenplays; frequent magazine contributor. I have four other books "in...more
|
|
|
|
|
ADRIAN JOELE
I have been involved in nutrition and weight management for over 12 years and I like to share my kn...more
|
|
|
|
|
MICHAEL BRESCIANI
Rev Bresciani is the author of two Christian books. One book is an important and concisely written b...more
|
|
|
|
