The creation of user documentation is a big component of any software project. Unfortunately, it’s often undervalued and left to last minute. But that doesn’t mean it should be without a good management plan.This is first in a series of three articles outlining key elements of a good user documentation process. It’s kind of an “ideal” process; very few projects will be able to implement every step, and some will require additional steps. Nonetheless, it should provide you with a good foundation (especially if you’re new to user documentation management).
Here’s an overview of three articles.
Article 1 (this article) – Understand
•Identify your scope •Familiarise yourself with work environment •Familiarise yourself with product •Identify audience for documentation •Specify perceived audience requirements •Roughly estimate doco project duration and resources •Research audience requirements
Article 2 – Specify (See http://www.divinewrite.com/docoprocess2.htm)
•State your goals •Write your concept specifications •Design some possible implementations •Conduct usability testing on your prototypes •Write your requirements specifications •Estimate project duration & resources •Conduct usability testing on your writing sample •Write your work pracs & design specs
Article 3 – Write (see http://www.divinewrite.com/docoprocess3.htm)
•Write doco •Manage production
So here goes…
Understand Your Project
Identify Your Scope
The first step in any project is to identify exactly what you’re expected to do. Generally this will happen before you take on job, but it should still be first thing that you document. Identifying your scope involves figuring out where you fit in overall development process and where you fit within company. No documentation project is ever just documentation, so it’s important to know exactly what else is involved. Some of other areas that documentation people are/should be commonly be involved in include:
•Spec review •GUI review •Product user requirements research •Documentation audience requirements research •Usability testing
All of these things are integral to development process, and should be scheduled properly.
Familiarise Yourself with Work Environment
Get to know everyone involved in product. For a software project, this will mean project manager, designers, and guys that will be doing low-level coding. Try to have a really good relationship with them. They have to respect you, otherwise they’re not going to listen to much of what you have to say.
Familiarise Yourself with Product
Find out what’s going to be involved in product. You must know:
•what are goals of development •what user requirements they are trying to meet •how product will be used •who will be using it •what features of product are •how product will look and feel •will it require a specific doco design? For instance, it may only run on latest version of Windows, it may have a particular look and feel, a particular environment (that help may have to be integrated into), etc.
These are all things that you may have input into, either through simple critique, or through input into user research requirements. Try to read as much documentation as you can find, and interview as many people stakeholders as possible. As you go, note down any issues you identify, any questions you have, or anything you think needs to be different.
Some (non-human) sources that you can utilise to achieve this include:
•Feature and product specifications •Project plans •Funding application documentation if applicable
Identify Audience for Documentation
Discuss with project manager (and other stakeholders esp. marketing) perceived user/audience.
Specify Perceived Audience Requirements
Make some educated guesses about audience requirements so you’ll be able to provide a rough estimate of product duration and resource requirements.
Discuss with project manager (and other stakeholders esp. marketing) perceived user requirements that help must satisfy. See if someone has researched user goals, tasks, and mental models users employ when using product (or similar products). If they haven’t, interview inhouse experts to identify perceived goals, tasks, mental models, etc.
Secondly, you should identify what theory says about user documentation (i.e. documentation approach, visual considerations, indexing considerations, etc.). I recommend Minimalism Beyond Nurnberg Funnel, (1998) edited by John M. Carroll.
Roughly estimate doco project duration and resources