RoboHelp Article

Planning User Documentation: A Guide for Project Managers

As a project manager, how do you fit user documentation into your project plans? Is it an afterthought - and only developed at the end of the project, just before a product launch, when resources are limited and deadlines are looming?

It needn't be like this. In fact, by including documentation writers earlier and at key stages of the project, you can add real value to your final product.

This article seeks to help project managers improve documentation, and the overall product that is being documented, by involving writers earlier in the product development plan.

Your Project Plan

A typical software project often comprises the following stages:

Figure 1. A typical plan for a software project.

A Traditional Documentation Project Plan

A typical documentation project often comprises the following stages:

Figure 2. The vertical gray bars represent review cycles (these bars are not to scale). Reviewing documentation can take longer than you think and somebody with expert knowledge of the software must perform the reviews.

Familiarize Yourself with the Documentation Process

Prototype: During the prototype stage, your writer creates a structured set of empty topics (pages of information) with a provisional look and feel. For each topic type, one is populated with content as a sample. The review process during this stage determines whether the structure is complete and suitable and whether the look and feel, writing style, and writing conventions are appropriate.

First draft: During the first draft stage, your writer creates the content for all the topics. This is the most time-intensive stage and therefore, takes the most time to review. The reviewer must make sure that the content is technically accurate.

Second draft: During the second draft stage, your writer makes necessary changes, based on the first draft review. The reviewer during this stage confirms whether the writer has made the necessary changes based on the first draft review and requests any minor tweaks still outstanding.

Final draft: This final draft stage follows up on the minor changes noted during the second draft review. The result is the final deliverable.

Fitting Documentation into Your Project Plan

Traditionally, the documentation process starts at the end of the testing stage of your project. However, I recommend that you involve the writer much earlier in the process. Getting the writer into the process earlier spreads the workload more evenly and reduces project risk. Moreover, including your writer in design decisions and usability testing can improve the user interface. Ultimately, you deliver a better experience to your users and receive fewer technical support requests.

Below you'll find tips and suggestions for modifying your process to integrate documentation into your overall project plan., As part of the first stage, you'll need to evaluate timescales and resources and appoint roles and responsibilities.

Evaluating Timescales and Resources

When thinking about timescales, remember—effective documentation takes time to develop. As seen in the typical documentation project plan above, the elapsed time can be much longer than just the writing time due to the review process. It's imperative that you factor in time for this.

Depending on the scale and complexity of your software, you might consider splitting the documentation between different writers. Authors working in parallel can speed up the process, but beware—the tool(s) you use to create the documentation, together with the associated workflow, may mean that this is not feasible. In addition, you must keep documentation consistent within the writing team. Besides providing the writing resources, it is just as important to provide adequate resources for reviewing. These resources include the reviewers and also a documentation manager, who must coordinate the reviewers with the writers. Factor all of these resources into the cost.

With so much to do in the testing stage, planning for documentation at this initial stage and the demands on expert staff for reviewing can create a project risk if you do not properly plan and resource it now.

Appointing Roles and Responsibilities

Choosing Writers

If your organization has a documentation department, your solution is simple. If not, consider the following alternatives.

The Programmers: Using the programmers as writers seems logical, they certainly know the product inside out. But beware. Programmers are experts in programming—not necessarily in communicating! They may assume the audience has a level of knowledge that it does not have. Moreover, their enthusiasm for their creation often gives them an understandable tendency to explain technical features in granular detail, focusing on product functionality rather than answering users’ questions.

A Contract Technical Writer: This is often a good solution, though it very much depends on your project plan. In the build stage of your project plan, you might set aside long stretches of time for coding software between tests. This could leave a contract technical writer idle, compromising your budget. As mentioned below, you could put the writer on other project-related tasks (ie., structuring the help system, labeling UI menus).

Outsourcing: By hiring an external organization to project manage and develop your documentation, you only pay for the days spent managing and writing. This solves the problem of idle time, but does have a couple of disadvantages. Since the writer is usually offsite, direct communication can be more difficult. Also, the particular writer you're using may be unavailable if timetables and deadlines change.

Choosing Reviewers

You may want or need more than one reviewer. As already mentioned above, documentation at every stage must be reviewed by at least one expert in the software. This ensures technical accuracy. In addition, it is often useful to get other relevant people to review parts of the documentation. For example, you might ask prospective end users to review content.

Managing the Documentation Process

The documentation project manager is necessary to coordinate the writing and the reviewing process. Unless your programmers write your documentation, most writers will have questions. Part of the documentation manager’s role includes coordinating questions and answers between the writer and the programmers.

If you choose to outsource, the external company manages the delivery of the drafts, the receipt of review points, and the writer’s questions for the programmers. However, you must still appoint a documentation project manager as a single point of contact for the external document project manager. Without this role, the external company may receive inconsistent information from the reviews, with review points contradicting one another.

Spreading the Content Creation

As mentioned above, the traditional close-to-launch timing of the documentation presents a project risk. To reduce the amount of time and resources required at this busy time, there are a number of tasks that your technical writer can tackle earlier in the process to reduce project risk.

Setting the Look and Feel of the Help system. These days, authoring tools for technical writers make it possible to create Help systems with a customized look and feel. Now, software houses want Help systems that are more visually interesting and similar to the software they create rather than the standard gray Help systems. For instance, you can create more customized Help systems with Macromedia RoboHelp. Creating a customized look-and-feel takes time, however. But this is one of the tasks your technical writer can do in the design stage, as soon as your team decides on the software's look and feel.

Structuring the Help system. Depending on the complexity of the software, it may be possible for the technical writer to sketch out a rough structure for the topics in the Help system after the design stage. This would be a flexible work-in-progress structure, but would at least set a draft of the types of information to be documented.

Gathering conceptual information. Generally speaking, the majority of Help topics in a Help system are procedural. They tell the user how to do something by providing detailed step-by-step instructions on using the interface. In general, the writer cannot create procedural topics until the software is more or less stable. However, there will also be some information for the user that is conceptual. It may be possible for your writer to document these concepts during and after the design stage.

Fitting Documentation into Your Project Plan

Figure 3. A summary of documentation in your project plan

Getting More Value from Your Technical Writer

Specifications and Design Stage

Because good technical writers often have expertise in designing information, they can also provide useful input at the specifications and design stage. Using your technical writer at this stage can help you create a more usable interface. This reduces your technical support costs and may reduce the time it takes to document the software. It may be something as simple as labeling or ordering the fields for the dialog boxes in a more helpful way. Moreover, writers with experience in writing for screens usually know which types of layouts work. They can provide valuable input for decisions on the structuring and the look and feel of the interface. Also remember that they are user-focused and can provide balance to an over-enthusiastic graphics design team. Think of the technical writer as the representative of your average user as you decide the software specifications and as the design progresses.

If your technical writer contributes expertise during the specification and design stage of the project, it may reduce the traditional paper manual/online Help documentation, or make it unnecessary. In other words, you may eliminate the need for certain documentation areas if and when you include a technical author at the design stage.

In some cases, the user interface can contain its own user assistance, an approach called Embedded Help. You decide how and where to provide assistance in the specification and design process. For example, one successful technique is to have a dedicated (but shrinkable) part of the interface for displaying context-sensitive assistance.

During the build stage: If the writer is present at all relevant meetings, it reduces the number of questions he or she will have for the programmers when writing the Help content. This saves precious time near the end of the project.

During the testing stage: If you plan to perform usability testing, your technical writer can participate in designing and giving the tests and in interpreting the results.

After rollout: If you are outsourcing your documentation, the external organization may provide a service for logging and collating user feedback, reporting it to you and updating the Help where appropriate.

Conclusion

Providing online assistance for software is important since it can reduce the cost of technical support and make life easier for your users. However, documenting software is not a trivial task. It requires time and resources for writing and reviewing that you must include in the overall project plan. Documentation work is traditionally implemented after the software is reasonably stable, during the testing stage. However, getting your writer into the process earlier spreads the workload more evenly, and reduces project risk. Moreover, including your writer in design decisions and usability testing can improve the user interface.

About the author