Successful Documentation Projects – Part 1 of 3 – ‘Understanding’
The creation of user documentation is a big component of any software project. Unfortunately, it’s often undervalued and left to the last minute. But that doesn’t mean it should be without a good management plan.
This is the first in a series of three articles outlining the 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 the three articles.
Article 1 – Understand
— Identify your scope
— Familiarise yourself with the work environment
— Familiarise yourself with the product
— Identify the audience for the documentation
— Specify perceived audience requirements
— Roughly estimate doco project duration and resources
— Research audience requirements
Article 2 – Specify
— 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
— Write the 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 the job, but it should still be the first thing that 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 ever 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 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 the development process, and should be scheduled properly.
Familiarise 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 that will be doing the 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 the Product
Find out what’s going to be involved in the product. You must know:
— what are the goals of the development
— what user requirements they are trying to meet
— how the product will be used
— who will be using it
— what the features of the product are
— how the product will look and feel
— will it require a specific doco design? For instance, it may only run on the latest version of Windows, it may have a particular look and feel, a particular environment (that the 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 the Audience for the Documentation
Discuss with the project manager (and other stakeholders esp. marketing) the 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 the project manager (and other stakeholders esp. marketing) the perceived user requirements that the help must satisfy. See if someone has researched user goals, tasks, and the mental models users employ when using the product (or similar products). If they haven’t, interview inhouse experts to identify perceived goals, tasks, mental models, etc.
Secondly, you should identify what the theory says about user documentation (i.e. documentation approach, visual considerations, indexing considerations, etc.). I recommend Minimalism Beyond the Nurnberg Funnel, (1998) edited by John M. Carroll.
Roughly estimate doco project duration and resources
Although, by this stage, you don’t really know enough about the product or your audience requirements to know how long the documentation will take to complete, management will nonetheless like a rough estimate. This is OK, as long as everyone is aware that it is a VERY rough estimate, and subject to change pending further knowledge and research.
This initial estimate must incorporate all of the time you’ll spend on the stages that occur before and after the writing stage. Remember, these stages are important, and should not be short-changed. (TIP: In a well managed project, planning should take approx 30% of your time, writing 50%, production 19%, and evaluation 1%.)
Estimating pre-writing stages
Allowing for the pre-writing stages is trickier than allowing for writing. If you’re having trouble, estimate the writing stage, then base all other estimates on that, using the above figures as a guide.
Estimating writing and post-writing stages
Because you probably still don’t know a great deal about the product or the users, your estimate here will be based primarily on a combination of past records, experience, intuition (gut feel), and industry standards in combination with the goals and tasks you’ve already specified. Start with the following steps.
1. Estimate the quantity of work required to document the tasks the user will need to perform to achieve their goals.
2. Track down any previous doco records. See if you can cross reference the time taken to produce similar doco in the past with the current quantity estimate. Derive a figure based on this method.
3. See how this compares with the estimate derived from industry standard figures (e.g., I think the current industry standard is to allow 1 day per page of documentation – this covers all drafts and reviews).
4. Compare the two figures and determine a good compromise based on your experience and intuition.
5. Figure out how long you actually have to do it, then how many writers you’ll need to get it done during this time.
6. Draw up a project schedule using something like Microsoft Project. Don’t forget to allow time for recruiting, training, and writing work practices.
TIP: At this stage, you should write the first draft of the Documentation Project Plan. It should include or refer to all of the steps outlined in this document. Basically, it should reflect the process advocated here, but be specific to the project you’re working on. It should also include a timeline.
Research Audience Requirements
Research on the users of the product and the audience of the documentation is one of the most important parts of any successful product. Unfortunately, it is also one of the most often overlooked aspects of any project. This generally occurs because decision makers feel they already know pretty much everything there is to know about the users and audience.
When managing a documentation project, you should investigate the chance of conducting research. If you’re employed late in the product life cycle, you should ask if user research has already been conducted for the product itself. If it hasn’t, there’s a good chance you won’t get support for audience research.
Audience research should seek to identify:
— user goals (what the user hopes to achieve with the product)
— user expectations of the doco (Manuals? Online help? Tutorials?, usability requirements, localisation requirements, etc.)
— user 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 what tasks (user/task matrix)
— how long have users been doing these tasks?
— which tasks are one-off and which are repeated?
— did they ever do them differently?
— do they do a variety of tasks, or just a few?
— do they hate doing it? (is it tedious, repetitive?)
— do they find it difficult?
— which tasks are considered essential?
— are they normally under pressure when they do the task?
— 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
Successful Documentation Projects – Part 2 of 3 – ‘Specifying’
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.
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:
— Ease of use
— Adherence to style guidelines
— Correct spelling and punctuation
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:
— what components the documentation suite will consist of (online help, printed manuals, tutorials, overviews, etc.) – “Documentation Products Concept Specification”
— the types of information your documentation will contain (e.g., the structure of the TOC, are you going to follow minimalism practices?) – “Documentation Content Concept Specification”
— the functionality and user interface of your documentation suite (e.g., how it will work and how the audience will interact with it) – “Online Help User Interface Concept Specification”, “Printed Documentation User Interface Concept Specification”, etc.
— the delivery method (how you will deliver the help to users and how you’ll update it)
— what languages the documentation will be produced in
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:
— the technologies behind them
— the tools used to create them
— the overall look and feel
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:
— List servers
— Other publications
— Other writers
— Other products
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).
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:
— what components the documentation suite will consist of (online help, printed manuals, tutorials, overviews, etc.) – “Documentation Products Requirements Specification”
— the types of information your documentation will contain (e.g., the structure of the TOC, are you going to follow minimalism practices?) – “Documentation Content Requirements Specification”
— the functionality and user interface of your documentation suite (e.g., how it will work and how the audience will interact with it) – “Online Help User Interface Requirements Specification”, “Printed Documentation User Interface Requirements Specification”, etc.
— the delivery method (how you will deliver the help to users and how you’ll update it)
— what languages the documentation will be produced in
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:
1. Compile a list of tasks, and record how many there are in your list.
2. Compile a list of concepts that must be documented, and record how many there are in your list.
3. From your list of tasks, select 10 that are representative of the rest (in terms of complexity, expected length, status of the relevant development, etc.), and of the same granularity (e.g., you can write a single topic for each).
4. From your list of concepts, select 3 that are representative of the rest, and of the same granularity (e.g., you can write a single topic for each).
5. Estimate the number of pages per topic.
6. Document these tasks and concepts as a trial, ensuring that you track:
— the total time taken to complete each topic.
— the portion of this time that was due to product change or indecision.
— the number of pages per topic.
— the number of extra, unexpected, but necessary, topics you became aware of as a result of the documentation. Keep a separate record of the number for both task and conceptual topics.
TIP: Make the most of your trial doco. Even though you’ve chosen a design through design prototyping, you can use your documentation sample to test the usability of your documentation approach. By presenting the sample to an audience sample, you can determine whether you’re heading in the right direction with your doco (i.e. whether you have interpreted and implemented your user research results correctly).
7. Determine the average time taken per page for task and for conceptual topics.
8. Apply this average to the rest of the topics in the project. (Topics written early in the project normally take longer due to lack of information and a higher number of technical issues. This means topics written later in the process will probably take less than the average calculated here. However, this will normally be offset by the extra time product changes will incur during the project life-cycle.)
9. Estimate the time per subject area based on the average time per topic.
10. Estimate the number of extra, unexpected, topics that will likely become necessary during the course of the rest of the project.
11. Allow for training, work prac maintenance, holidays, sick days, meetings, usability testing, production (approx 6 weeks turnaround time for printing a 1000 page manual, including proofing), evaluation, and evaluative testing. Each of these elements will vary according to the nature of the project, and they will tend to take far less time than the actual writing. That is why specific guidelines are not provided as they are for writing.
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:
— Prototype Testing Complete
— Work Pracs Written
— Design Specs Written
— First Draft Complete
— Second Draft Complete
— Localisation of Second Draft Complete
— Final Draft Complete
— Localisation Complete
— Documentation Ready for Release
— Production Complete
— Project Evaluation Complete
— Post-release Usability Testing Complete
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.
Successful Documentation Projects – Part 3 of 3 – ‘Writing’
So you understand your user documentation project and you’ve specced it out. Now you’re ready to write. Here’s some tips to help you on your way. This article isn’t about the actual writing itself; it’s about the things which go along with the writing.
Index keywords should be defined while the topic is being written. At this time, the subject matter is clear in the author’s mind, and they are very conversant with all of the intricate details. Indexing during the writing stage also means that your keywords are reviewed as part of the draft process.
Some authoring tools don’t really facilitate this kind of approach particularly well (e.g., some don’t allow multiple author access to the files needed for indexing), but at least the keywords should be listed at the end of each draft. (Depending on the authoring tool, this may actually be easier for the reviewers, anyway.)
User documentation reviews
To ensure that your user documentation is technically correct and readable, you need to get it reviewed by an intelligent selection of people. For a software project, your review list should include a subject matter expert (generally the programmer), the software architect, perhaps the project manager, and another writer. The review requirements will vary with each draft, so your reviewers and review procedures should be documented in your work pracs.
Testing your user documentation
Testing can be performed at a number of levels:
— Each writer should test their own user documentation by following it to use the product. But remember, this kind of testing isn’t very powerful, because there’s a tendency for writers to follow instructions as they think they’ve written them, not as they’ve actually written them.
— The second level is for the testing to be performed by other writers… as part of the peer review.
— The third level is for the testing department to do formal testing on the user documentation. This type of testing doesn’t often happen, but it’s good to try to get it happening.
— The fourth level is/should be conducted as part of Beta testing (see Managing Your Documentation Projects by Hackos (1994), pp.452-453).
No matter what level of testing you use, it should be designed to ensure that the tasks documented are true to the product, and that any online help functions correctly. For the user documentation to pass testing, it needs to satisfy the goals you specified in the earlier stages of the project.
Localising your user documentation
Although localisation is often considered a post-writing activity, it’s best to do it as part of the writing stage. The exact timing may vary project to project, but a good rule of thumb is to get the translators working on the second drafts (but only if you’re not expecting many changes to the draft). TIP: Most translators will probably prefer to work on a sizable piece of user documentation, rather than individual topics sent to them piece-meal, so you should wait ‘til you have something of a respectable size to send them – perhaps a whole subject area, as opposed to a single topic.
With localisation, you’re performing a balancing act. If you send the user documentation to the translators too soon, you’ll spend a lot of money on changes to the translations. If you send it too late, it won’t be ready in time for the release of the product.
It’s important that you minimise the impact of changes to the product and/or development schedule. To do this, you need to develop a technique which:
1. Identifies the change
2. Estimates the impact in time and/or resources *
3. Informs the project manager
* You can use the same estimating techniques as you used earlier in the project.
Tracking writing progress
It is important to note that the writing stage is not simply about writing. If you track your progress at every step along the way, you’ll be able to see whether you will meet your milestones and deadlines, and you’ll also be able to use this project as a learning experience… to better plan the next one. (You should ensure that all project records are easily accessible for ongoing maintenance and future project reference.)
You should track the time taken to perform every step outlined in this procedure as well as each draft stage, review times, total turnaround times, etc.
Conducting regular team meetings
In order to keep all team members informed of writing progress, you should conduct regular team meetings. These meetings should be a forum for taking a look at your tracking metrics and discussing the estimated percentage complete for the various topics currently under way. If the estimated percentage complete is lower than it should be given the time already spent, then you can act on it. These meetings allow you to identify hitches in the writing progress.
Writing progress reports
Your management also need to be kept informed of the status of the project. You should write periodic progress reports outlining:
— Where the project is at
— What you’ve done over the last month
— What you plan to do over the next month
— Any issues you’ve encountered
The meaning of “production” varies depending on what kind of documentation you’re working on and who the audience is. It can encompass such things as:
— Product build (when the help is compiled into the product)
Although the production stage generally only requires management, you still need to spend a fair bit of time on proofing and liaising with production people.
Evaluate the Project
The purpose of the evaluation stage is to consider:
— Did the project go according to plan?
— Why? / Why not?
— How individual team members contributed to the overall project.
— How the project manager performed.
— Whether the documentation achieved its goals.
Your tracking metrics will come in handy during this stage; if there were any flaws in the project progress, they should go some way towards identifying them. You might also use the sample evaluation report provided by Hackos in Managing Your Documentation Projects by Hackos (1994), pp.514-518.
Is your documentation successful?
Now that you’ve written and released the documentation, you need to determine whether it has achieved your goals. The only way to accurately do this is to conduct further user research.
And that’s it! Remember, this process is an ‘ideal’ process. Take the bits that suit you and your project, and leave the bits that don’t.
0. The coming of the prophet 1. Love 2. Marriage 3. Children 4. Giving 5. Eating and Drinking 6. Work 7. Joy and Sorrow 8. Houses 9. Pets 10. Clothes 11. Buying and Selling 12. Crime and Punishment 13. Laws 14. Freedom 15. Reason and Passion 16. Pain 17. Self-Knowledge 18. Teaching 19. Friendship 20. Talking 21. Time and Space 22. Good and Evil 23. Prayer 24. Pleasure 25. Beauty 26. Religion 27. Death 28. Forms Of Existence 29. Real vs Virtual 30. The Farewell