ProjectConnections.com Template User Documentation Plan
INTRODUCTION: User Documentation Plan
|
The Guideline and Template Content Starts on the Following Page
What This Is
A plan for the creation of the user documentation for a product, application, or service. Examples of this documentation might include:
Use guides, installation guides, and troubleshooting manuals
Box inserts
Training manuals and presentation
Online help
The checklist helps to ensure that this documentation is planned early in the project, all work involved in creating the documentation is identified, and ownership of both technical writing and development team input tasks is established. Some sample documentation items are shown in the checklist.
Why It’s Useful
All too often, the tasks for user documentation are not incorporated early into the work breakdown and schedule of a project. This lack of early warning to the group responsible for such publications puts a strain on their technical writer resource planning. Lack of early planning also hides the work that the team itself must contribute to the documentation effort. This can result in an either an expensive delay to getting to market or poor quality documentation that is rushed at the last minute.
How to Use It
Create these elements of a full User Documentation Plan as you move through your project:
Documentation Overview (Section 1 of this template): Write a rough high-level version of the plan during the Initiation/Planning phase of the project, to help identify the scope of user documentation required to support the product, application, or service being created. This can be as simple as creating the Documentation Overview Table discussed on pages 2 and 3.
Content Plan (Section 2 of this template): Create a Content Plan during the project to further define the scope and design of the needed user documentation. Section 2 shows how to create a more detailed outline of the major sections of all the publications.
Development Timeline and Estimates (Section 3 of this template): Provide first rough estimates of staffing and financial resources required to develop that documentation to the project manager as part of early project planning and budgeting. Update your estimates and refine the document creation schedule as your understanding of the documents’ content and length is worked out.
Further steps for creating each part of the User Documentation Plan are included on the following pages.
|
The Guideline and Template Content Starts on the Following Page
User Documentation Plan
Section 1: Documentation Overview Table
This section makes sure the team has thought through all the documentation that is needed.
Use the table format on the following page to:
List all of the user and support documentation items for your project.
Spell out the purpose and audience for each item. These two elements will have critical impacts on how much has to be written, in what style, at what level of detail; and will also help determine who needs to be involved in documentation reviews.
Assign both a writer as “Writer/Owner” and a team person as “Subject Matter Expert (SME) Contact.”
The Writer/Owner is responsible for driving the writing tasks. They may also design the documentation and write and editing the content; or those tasks may be delegated, depending on the size and nature of the documentation. Regardless, the Writer/Owner is responsible for executing the schedule and ensuring the publications are being created according to spec.
The SME Contact is responsible for providing information for the writer through interviews and relevant marketing and product/service/application information. The SME Contact is also responsible for reviewing documentation drafts. The SME Contact may involve other SMEs as needed for all the content to be developed; but the SME is the single-point contact and responsible person.
During planning, use the “Pub Date” column to indicate when initial printed quantities of the finished item are needed. Then use Start Date as an estimate when actual work must begin on the item in order to achieve the Pub Date. This will help the publications group identify the overall scope of work and do initial resource planning. You should then include in the project’s work breakdown structure (WBS) the detailed information transfer and review tasks, schedule them with named resources, and get the Writer/Owner and the SME Contact’s commitment to this schedule.
Use the “Notes” field to call out any special requirements or schedule dependencies for the item that you don’t want to forget during detailed planning.
If foreign language translations are required, they should be explicitly listed as items, and the translation process should appear as tasks in the project’s work breakdown.
To use the example table shown on the next page, simply change the descriptions and add any documentation specifically needed by your project. Refine the checklist with the manager(s) responsible for creating this documentation and get their commitments for resources.
See table next page
Documentation Overview Table
Item
|
Purpose
|
Audience
|
Writer/
Owner
|
SME Contact
|
Reviewers
|
Start Date
|
Pub Date
|
Notes (with typical content as example)
|
Users Manual
|
Reference manual for details of how to use certain features of the software.
Provide case studies also to show how to use it in specific situations.
Provide instructions for how to customize.
|
All users of the software:
Hands-on users
Consumers of output reports
Partners
Person at client doing customization (reports, interface)
|
|
|
|
|
|
Cautions and license terms to be reviewed by Legal.
Determine whether online help and written reference manual will be sourced from same material.
|
Quick-Start Guide
|
Provide instructions for fast start-up using the software.
|
All users of the software.
|
|
|
|
|
|
Limit initial production quantities, as web-based customer service descriptions are expected to change in 4th quarter.
|
On-line help
|
First line of reference when users have a question as they're using software.
|
All users
|
|
|
|
|
|
Determine whether online help and written reference manual will be sourced from same material.
|
Training courses
|
Quickly train users of the software to obtain the business answers they need with minimum of time. Internal hand-off training for customer support personnel
|
All customers who will use the software. Daily hands-on users for data entry & low-level planning; and for interpretation of reports.
Internal customer support personnel
|
|
|
|
|
|
May have to create different courses or course modules for different users in the audience. See detailed training development plan.
|
Section 2: Content Plan for One or More Publications
This section provides the writers’ detailed analysis of the content to be developed, including how it will be organized. It organizes the publication and provides a rationale for the organization and detailed contents. It also helps the team develop a more detailed resource estimate and schedule for creating each document.
Include the following information for each publication:
Goals and objectives of the publication
Audience and the tasks the audience will perform and thus the types of instructions the audience will need: I.e. installation, maintenance, configuration, etc.
Resulting first draft document outlines, including a complete table of contents and outline of each section.
Draft cycles and reviews needed of publication at different stages of development
The result gives the team a thorough work breakdown structure for the rest of the publications’ development life cycle.
NOTE: You may start with one large table of contents, with multiple sub-sections that will be expanded into different technical publications when the documents are actually written. Doing it this way has the benefit of allowing the publications group to determine which content might be single-source developed, then used in multiple publications (e.g. in printed user manual, in online help or tutorial, and/or in a training course).
The work breakdown structure resulting from this content planning effort can then be used in Section 3 as a basis for planning timeline and estimating resources for creating the actual documentation.
See the example outline on the following page.
Example Outline for One Publication’s Content Plan
Publication name: Quick Start Guide
Goals and Objectives: Provide small, quick-to-read card of no more than 6 pages to help a new user get the product set up and running.
Key tasks to be covered by the publication:
Attachment of cables
Introduction paragraph
Drawing of all cable connections
List of each cable, name and purpose mapped to drawing
Steps showing order of hooking up cables
Start-up of Unit
Instructions for turning on power
Brief troubleshooting ideas if issue occurs
Installation of software
Instructions for loading CD-ROM and invoking start-up
List of software functions included on disk
Step-by-step for running installation program
Table showing choices during install and recommendations for settings
Start of application after installation complete
Start-up Self-Test results
Description of Self-Test functions
Expected results
What to do if self-test has error
Basic configuration
Description paragraph about what needs to be configured at start-up
List of required configuration settings and options
Troubleshooting
Intro paragraph
Table for common problems
Customer support reference if table doesn’t fix issues
High-level Work Breakdown including Review Sequence:
Content plan
Content plan creation
Content plan review and update
First draft creation – text and tables; leave space for drawings – estimated size
First draft writing
First draft review
Second draft
Second draft creation from feedback – update all text plus add drawings
Second draft review
Beta test use
Updated version for use at customer beta test
Update draft from beta test feedback
Final version
Ready final version
Final copy review
Cleanup
Release to printer
First printing
Review first article received from printer
Approve for full initial print run
Section 3: Development Timeline and Estimates
This section provides approaches for developing a timeline and detailed task estimates for both Printed User Manuals, and for Online Help for a software application, two typical types of user documentation.
3a. Printed User Manuals
Typical phases and steps:
The documentation creation can be broken down into logical phases and steps of work.
An example is shown below. Adapt these to your project and used to plan and estimate your documentation development timeline during the project.
Record your timeline and any assumptions as part of your User Documentation Plan. The estimate can be created in a spreadsheet or word processor, or using a scheduling tool.
Design:
Create Content Plan (Detailed outline – usually a 3-level table of contents)
Review outline – Subject Matter Experts, marketing, customer support, other interested parties
Investigate printing options: provide specs to multiple printers, get quotes
Development:
Create first draft, usually without much art
Perform SME content review and edit of first draft; do a copy edit if there's time
Create second draft, complete with art and index
Perform SME content review and edit, as well as full copy edit, of second draft
Alpha/Beta test **:
Use in pilot training courses for internal customer support personnel
Use in “Beta test” ** of software etc. with customers
Make final updates; should only be minor changes
Proofread entire document
Create final index
Production:
Submit master to printer
Get proof back from printer
Approve first production run.
Get first run back from printer
** Beta test is a term used to describe having customers use the product/service/application before it is widely released, in order to get feedback in a controlled customer environment, and have the opportunity to correct issues before general release. Not only should the primary product/service/application be tested during a Beta; the accompanying user documentation should be “tested” as well, by having the customer refer to the document as they try the product.
Estimating the timeline to execute the above – Include these elements in your user manual estimates:
Look and Feel: Plan for design time for determining the look and feel of the manual, page layouts, cover design.
Artwork and Graphics: Plan time for artwork and graphics creation. Will include conceptual sketches, review, creation of production quality artwork.
Writing time: Use the earlier content definitions of modules and estimate writing time per module. Modules can be broken down further into their typical components to use for bottom-up estimates, e.g.
Configuration procedure
Procedures for using each feature, along with explanations of their functions
Descriptions of all reports that can be printed
Resources: Determine whether you have multiple resources who can work on sections of the manual in parallel, or whether one person will have to do the modules sequentially.
Review cycles: Be sure to estimate adequate time for review of the documents by typical users and knowledgeable company members. For every review cycle, include 1 day or so of preparation, 1 day to review, 2 days to update after the review. Plan for 1-2 weeks elapsed time for each review cycle depending on how busy people are.
Some estimates guidelines from ProjectConnections.com contributors, based on a single writer:
User's Guide – 5 hours per page, including research
Reference Guide – 4 hours per page, including research
API Guide – 3-7 hours per function, depending on research and methodology
Online help (traditional) – 5 hours per topic
Online help (updating) – 1.5 hours per topic
Context-sensitive help – 3-4 hours per topic
Web pages – 8 hours per page
Due to consistency issues, the use of multiple writers may actually increase the amount of time required. Extremely technical information or information that must be acquired without availability of the product will also increase time requirements.
Another set of rules of thumb:
Project setup: In general, allow a minimum of 16 hours for research and preparation. Setup varies from project to project. Technical complexity is usually the governing factor – a 500-page reference manual might consume over two weeks in research and preparation.
Calculate total writing time:
(number of simple pages) x 1 hour/page
+ (number of moderate pages) x 2 hours/page
+ (number of complex pages) x 4 hours/page
Calculate total illustration time:
(number of simple graphics) x 1 hour/graphic
+ (number of moderate graphics) x 3 hours/graphic
+ (number of complex graphics) x 6 hours/graphic
Combine writing and illustration times if you are doing both. Otherwise, assume that writing and illustration happen in parallel.
Add a minimum of 40 hours (5 business days) for formal review.
Add 80 hours (10 business days) for production and printing.
Depending on your print vendor’s location, add at least 8 hours (1 day) for delivery.
3b. Creating Online Help
Typical steps for creating online help: These steps should be adapted to your project and used to plan and estimate your documentation development timeline during the project. Record your assumptions in the User Documentation Plan.
Design:
Outline (usually a 3-level table of contents)
Review of outline by tech, marketing, other interested parties
Development:
First draft, usually without much art
Technical edit of first draft; copy edit if there's time
In parallel, create all needed art
Second draft, complete with art and index; submit to build for test integration
Integration and Test
Hook up context sensitive help (either writer provides IDs to programmer, or vice versa)
Tech/copy edit of second draft; test of context sensitivity
Final draft; should only be minor changes
Proofread
"Deploy"
Submit to build for official inclusion in released software
Estimating the timeline to execute the above. The complexity of the software plays a big part in the estimate of time to create online help.
One writer's rule of thumb:
"General rule that 100 printed pages translates into ~250 online help topics, which translates into about 6 weeks (30 days) including indexing, art, editing, and proofreading. One thing to take into account when scheduling online Help is that you can schedule right up to the final build date, which gives you several weeks over printed documentation which usually has to go out to a printer with a 2-4 week turnaround.
Items to consider: what staff does the company have: just writers, or also editors, indexers, and production folks? IF you're creating multiple kinds of documentation, is the online help being written from scratch, or will it be created from material written for the printed manual?"
Another set of rules of thumb:
Project setup: Allow a minimum of 16 hours for research and preparation. Allow at least another 16 if you are also doing the design and layout. Allow at least 8 hours for the two or three thousand discussions about layout that will occur because everyone has an opinion.
Calculate total writing time using the same formulas for hard copy on previous page, but make allowances for the type of online copy being written. Online help systems usually translate fairly well, with a “page” of text being a single help file.
The same goes for total illustration time. However, do not neglect the time sometimes needed for tweaking images for online display.
Add a minimum of 40 hours (5 business days) for formal review.
Add 4 hours for final link verification, proofing, and spell checking
Copyright 2002-2006 Emprend Inc. / ProjectConnections.com. Permission for Members’ use on their projects. Page
See our Terms of Service for information on PMO/group use and corporate subscriptions.
|
