Successful Documentation Projects – Part 1 of 3 – ‘Understanding’

Creating user documentation is a large component of any software project. Unfortunately, it is often underestimated and left to the last minute. But that does not mean that it should be without a good management plan.

This is the first in a series of three articles describing the key elements of a good user documentation process. It’s a kind of “ideal” process; very few projects will be able to implement each step, and some will require additional steps. However, it should give you a good foundation (especially if you’re new to managing user documentation).

Here is an overview of the three articles.

Article 1 (this article) – Understand

• Identify your scope
• Familiarize yourself with the work environment.
• Get familiar with the product
• Identify the audience for the documentation.
• Specify perceived audience requirements
• Roughly estimate the duration and resources of the doco project
• Research audience requirements

Article 2 – Specify (See http://www.divinewrite.com/docoprocess2.htm)

• state your goals
• Write the specifications of your concept
• Design some possible implementations
• Perform usability tests on your prototypes
• Write your requirements specifications
• Estimate project duration and resources
• Perform usability tests on your writing sample
• Write down your work practices and design specifications

Article 3 – Write (see http://www.divinewrite.com/docoprocess3.htm)

• write the document
• manage production

So here goes…

Identify your scope

The first step in any project is to identify exactly what you are expected to do. Generally, this will happen before you take on the job, but it should still be the first thing you document. Identifying your scope involves figuring out where you fit in the overall development process and where you fit within the company. No documentation project is just documentation, so it’s important to know exactly what else is involved. Some of the other areas that documentation people are/should be commonly involved in include:

• Specification review
• GUI overhaul
• Investigation of product user requirements
• Documentation Hearing Requirements Investigation
• usability testing

All of these things are an integral part of the development process and must be scheduled accordingly.

Familiarize yourself with the work environment

Get to know everyone involved in the product. For a software project, this will mean the project manager, the designers, and the guys doing the low-level coding. Try to have a very good relationship with them. They have to respect you, otherwise they are not going to listen to much of what you have to say.

Get familiar with the product

Find out what is going to be involved in the product. You must know:

• what are the development goals
• what user requirements are they trying to meet
• how the product will be used
• who will use it
• what are the characteristics of the product
• how the product will look and feel
• Will it require a specific doco design? For example, it might only run on the latest version of Windows, have a particular look and feel, a particular environment (where help needs to be integrated), etc.

These are all things you can get involved in, either through simple criticism or through input in user research requirements. Try to read all the documentation you can find and interview as many interested people as possible. As you go, write down any problems you identify, any questions you have, or anything you think should be different.

Some (non-human) sources you can use to accomplish this include:

• Product features and specifications.
• project plans
• Documentation of the financing request, if applicable.

Identify the audience for the documentation

Discuss with the project manager (and other stakeholders, especially marketing) the perceived user/audience.

Specify perceived audience requirements

Make some educated guesses about your audience requirements so that you can provide a rough estimate of product life and resource requirements.

Discuss with the project manager (and other stakeholders, especially marketing) the perceived user requirements that the aid should satisfy. See if anyone has researched user goals, tasks, and the mental models users employ when using the product (or similar products). If they haven’t, interview internal experts to identify perceived goals, tasks, mental models, etc.

Second, you need to identify what the theory says about user documentation (ie, documentation approach, visual considerations, indexing considerations, etc.). I recommend Minimalism beyond the Nuremberg funnel(1998) edited by John M. Carroll.

Roughly estimate the duration and resources of the doco project

Although, at this stage, you don’t know enough about the product or your audience’s requirements to know how long it will take to complete the documentation, management will want a rough estimate. This is fine, as long as everyone knows that this is a VERY rough estimate and is subject to change pending further insight and research.

This initial estimate should incorporate all the time you will spend on the stages that occur before and after the writing stage. Remember, these stages are important and should not be underestimated. (TIPS: In a well-managed project, planning should take up about 30% of your time, writing 50%, production 19%, and evaluation 1%).

Pre-writing internship estimate

Allowing pre-write is more complicated than allowing writing. If you’re having trouble, calculate the writing stage, then base all other estimates on that, using the figures above as a guide.

Estimate of writing and post-writing internships

Since you probably don’t know much about the product or users yet, your estimate here will be based primarily on a combination of past records, experience, intuition (intuition), and industry standards in combination with the goals and tasks you’ve already specified. Get started with the following steps.

1. Estimate the amount of work required to document the tasks the user will need to perform to achieve their goals.
2. Track any previous doco records. See if you can cross-reference the time it took to produce a similar document in the past with the current estimated quantity. Derive a figure based on this method.
3. See how this compares to the estimate derived from industry standard figures (for example, I believe the current industry standard is to allow 1 day per page of documentation – this covers all drafts and revisions).
4. Compare the two figures and determine a good compromise based on your experience and intuition.
5. Figure out how much time you actually have to do it, then how many writers you’ll need to do it during this time.
6. Create a project schedule using something like Microsoft Project. Don’t forget to allow time for recruiting, training, and writing internships.

TIPS: At this stage, you should write the first draft of the Documentation Project Plan. You must include or reference all steps described in this document. Basically, it should reflect the process recommended here, but it should be specific to the project you’re working on. You should also include a timeline.

Investigative Hearing Requirements

Research on the users of the product and the audience for the documentation is one of the most important parts of any successful product. Unfortunately, it’s also one of the most often overlooked aspects of any project. This usually happens because the decision makers feel that they already know almost everything there is to know about the users and the audience.

When managing a documentation project, you should investigate the possibility of conducting research. If you are employed at the end of the product’s life cycle, you should ask if user research has already been done for the product itself. If not, chances are you won’t get audience research support.

The hearing investigation should try to identify:

• user objectives (what the user hopes to achieve with the product)
• Doco user expectations (Manuals? Online help? Tutorials?, usability requirements, localization requirements, etc.)
• users’ mental models (how they already see online help, what impressions they have of it, etc.)
• user tasks (how the user uses the product to achieve their goals)
• which users perform which tasks (user/task matrix)
• How long have users been performing these tasks?
• Which tasks are unique and which are repeated?
• Have they ever made them differently?
• Do they do a variety of tasks, or just a few?
• Hate doing it? (is it tedious, repetitive?)
• is it difficult for you?
• What tasks are considered essential?
• are they usually under pressure when doing homework?
• Are there other distractions (environmental, social, etc.)?

Some research methods to consider are:

• Observation of users doing their work in their work environment
• Focus groups and interviews with users
• Questionnaires

TIPS: For more details on these methods, take a look at Management of your documentation projects by Hackos (1994), User and task analysis for interface design from Hackos & Redish (1998), Social marketing: new imperative for public health by Manoff (1985), Qualitative Research Design 2nd Edition by Marshall & Rossman (1995), and “Conducting Focus Groups: A Guide for First-Time Users,” in Marketing planning and intelligence by Tynan and Drayton (1988).

To be continued… See Part 2 of this article (http://www.divinewrite.com/docoprocess2.htm) for information on preparing your specifications.