So you’re responsible for managing a documentation project. You know who your audience is, what they’re trying to achieve, how the product enables them to achieve it, and what the audience requires of the help. Now it’s time to spec out your intentions.
NOTE: This is the second in a series of three articles outlining the key elements of a good user documentation process. (To read the first and third articles in this series, go to http://www.divinewrite.com/docoprocess1.htm and http://www.divinewrite.com/docoprocess3.htm)
State your goals
Generically speaking, your goal statement should indicate that you hope to create a suite of documentation products that will satisfy audience requirements. Specifically, you’ll have a number of sub-goals. (TIP: It may help to remember that the goals you set here will need to be used to measure the success of your product through your own in-house testing as well as through evaluative user research.) Such sub-goals may include:
Write your Concept Specifications
Your goals set, you can start to contemplate what you’re going to produce. The first step is to create some concept specifications. Simply put, concepts specs are very high level overviews of what you’re proposing to produce. For example, your concept spec for the online help might state that you will be producing a product that allows the user to access information using a TOC, an Index, and a Find. It might suggest some possible GUI features of these elements, but it will not lay down requirements; just possibilities. The concept spec for your manuals might state that they will be professional looking, will contain many professionally drawn pictures, will have adequate white space, will be stylish, will be divided into chapters to match the task oriented nature of the online help, etc.
Generally, the product you’re proposing could be implemented in a number of different ways. You should write one or more concept spec(s) for:
Design some possible implementations
Now that you’ve decided roughly what you’d like to produce, you can design some possible implementations of it. Your designs will be very high level and they may not actually work (they may actually be just paper prototypes).
With most other considerations already finalised through your user requirements research, these implementations should only differ as a result of:
You need to learn as much as possible about these things, in order to determine what is actually possible, successful, effective, etc. You should be aware of current trends, literature, white papers, etc. This information can be obtained from a variety of sources. Some good places to start include:
Conduct usability testing on your prototypes
Model (prototype) your designs for the decision makers and audience samples. This allows you to pick the best features from each design (and to determine priorities for them). Select a design (or merge multiple designs) that you believe best satisfies user requirements. This process may be iterative. At the end of this stage, you should know enough to detail exactly what you’ll be producing (including what help platform and tool you’ll be using).
TIP: For details on possible research methods, take a look at Managing Your Documentation Projects by Hackos (1994) esp. pp.446-447, User and Task Analysis for Interface Design by Hackos & Redish (1998), Social Marketing: New Imperative for Public Health by Manoff (1985), Designing Qualitative Research 2nd Edition by Marshall & Rossman (1995), and “Conducting Focus Groups – A Guide for First-Time Users”, in Marketing Intelligence and Planning by Tynan & Drayton (1988).
Write your Requirements Specifications
Requirements specifications detail exactly what you must end up with. These specifications should contain as much detail as possible about the features and functionality of the documentation product (not how you’ll go about building it).
Requirements specs are basically an evolution of your concept specs. Once you begin work on your requirements specs, the concept specs are effectively frozen. You should write one or more concept spec(s) for:
Estimate Project Duration & Resources
Once you’ve completed the requirements spec stage, you should know enough to accurately estimate the duration and resource requirements for the remainder of the project. You should also update the “Documentation Project Plan” document with this information.
Estimating is always a difficult process, and there’s not really any sure-fire way of getting it right. Mostly it depends on the job and your experience. However, following are some guidelines that might help you.
If you have records from previous projects, you might simply be able to estimate project duration based on these. You should try to compare the old subject material and topics with the new to make sure that the old times will be applicable to the new project. On p.174 of Managing Your Documentation Projects (1994), Hackos provides some potentially useful guidelines for comparing the complexity of various documentation projects.
If, on the other hand, the project is entirely new, you will have no records to use as a guide (unless you have managed a similar project in the past). In this situation, project estimates will be very difficult to make.
One possible method for estimating is:
Figure out how long you actually have to do it, then how many writers you’ll need to get it done during this time. Draw up a project schedule using something like Microsoft Project, identifying useful milestones and project deadlines. Some of your milestones might include:
It is important to note that you will have milestones before this point, but because they occur prior to the formal scheduling stage, they don’t need to be included in this schedule.
Write Work Pracs & Design Specs
Along with user research, work pracs and design specs are perhaps the easiest project elements to overlook, especially for a small team. However, even within small teams, it is helpful to maintain both.
Work pracs are for ongoing things, that affect the day to day working environment of the team (e.g., How to use your documentation tool, How to release your help, a style guide, etc.). Design specs are for documenting one-off things like how we actually plan to go about this thing. This will include such information as what tools we’ll be using, what each will do, and the mechanics of how it all fits together. e.g., How the VSS project will work, how everything should be managed, multi-user issues, how it will be localised, etc.
To be continued… See part 3 of this article (http://www.divinewrite.com/docoprocess3.htm) for information on writing your user documentation.
Is the Internet history’s greatest hoax?
For a while there, the Internet and the World Wide Web showed great promise. They whispered sweet nothings in our ears, promising to be the voice of the marginalized, the new democracy, the great equalizer.How and when should I submit my website to Google?
As soon as you register your domain name, submit it to Google!A Day in the Life of a Freelance Copywriter
Ever wanted a job where you could spend all day, every day, writing clever and ... prose? Yes? Well don’t become a ... ... get me wrong, it’s a great job, and for some of us