User Documentation Plan




Download 62.32 Kb.
NameUser Documentation Plan
A typeUser
manual-guide.com > manual > User

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:

  1. Attachment of cables

    1. Introduction paragraph

    2. Drawing of all cable connections

    3. List of each cable, name and purpose mapped to drawing

    4. Steps showing order of hooking up cables

  2. Start-up of Unit

    1. Instructions for turning on power

    2. Brief troubleshooting ideas if issue occurs

  3. Installation of software

    1. Instructions for loading CD-ROM and invoking start-up

    2. List of software functions included on disk

    3. Step-by-step for running installation program

    4. Table showing choices during install and recommendations for settings

    5. Start of application after installation complete

  4. Start-up Self-Test results

    1. Description of Self-Test functions

    2. Expected results

    3. What to do if self-test has error

  5. Basic configuration

    1. Description paragraph about what needs to be configured at start-up

    2. List of required configuration settings and options

  6. Troubleshooting

    1. Intro paragraph

    2. Table for common problems

    3. Customer support reference if table doesn’t fix issues


High-level Work Breakdown including Review Sequence:

  • Content plan

    1. Content plan creation

    2. Content plan review and update

  • First draft creation – text and tables; leave space for drawings – estimated size

    1. First draft writing

    2. First draft review

  • Second draft

    1. Second draft creation from feedback – update all text plus add drawings

    2. Second draft review

  • Beta test use

    1. Updated version for use at customer beta test

    2. Update draft from beta test feedback

  • Final version

    1. Ready final version

    2. Final copy review

    3. Cleanup

    4. Release to printer

  • First printing

    1. Review first article received from printer

    2. 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:

  1. Create Content Plan (Detailed outline – usually a 3-level table of contents)

  2. Review outline – Subject Matter Experts, marketing, customer support, other interested parties

  3. Investigate printing options: provide specs to multiple printers, get quotes


Development:

  1. Create first draft, usually without much art

  2. Perform SME content review and edit of first draft; do a copy edit if there's time

  3. Create second draft, complete with art and index

  4. Perform SME content review and edit, as well as full copy edit, of second draft


Alpha/Beta test **:

  1. Use in pilot training courses for internal customer support personnel

  2. Use in “Beta test” ** of software etc. with customers

  3. Make final updates; should only be minor changes

  4. Proofread entire document

  5. Create final index


Production:

  1. Submit master to printer

  2. Get proof back from printer

  3. Approve first production run.

  4. 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.

  • Installation procedure

  • 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:

  1. Outline (usually a 3-level table of contents)

  2. Review of outline by tech, marketing, other interested parties


Development:

  1. First draft, usually without much art

  2. Technical edit of first draft; copy edit if there's time

  3. In parallel, create all needed art

  4. Second draft, complete with art and index; submit to build for test integration


Integration and Test

  1. Hook up context sensitive help (either writer provides IDs to programmer, or vice versa)

  2. Tech/copy edit of second draft; test of context sensitivity

  3. Final draft; should only be minor changes

  4. Proofread


"Deploy"

  1. 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.

Share in:

Related:

User Documentation Plan iconThis documentation and any related computer software help programs...

User Documentation Plan iconUser documentation

User Documentation Plan iconUser's Documentation

User Documentation Plan iconUser documentation

User Documentation Plan iconUser Documentation

User Documentation Plan iconNew User Documentation for iPhone

User Documentation Plan iconPolygon End-User Documentation

User Documentation Plan iconUser manual and other documentation. Testing and Reporting

User Documentation Plan iconUser Guides and other documentation for all these scanners can be found

User Documentation Plan iconPhpexcel User Documentation – Reading Spreadsheet Files

User Documentation Plan iconAn automated coding and documentation improvement system that uses...

User Documentation Plan iconThis Restaurant Business Plan has been written to use a starting...

User Documentation Plan iconThe Annual credit Plan has been prepared with aggregate credit plan...

User Documentation Plan iconUser Information Plan

User Documentation Plan iconUser Information Plan

User Documentation Plan iconUser Information Plan

User Documentation Plan iconD a z z L e the Ultimate Graphics Image Generator Shareware Usage...

User Documentation Plan iconSample plan xyz transit asset management plan mission Statement

User Documentation Plan icon2Vendor Documentation Documentation can be found on the cd shipped...

User Documentation Plan iconUser’s Guidelines Part I general Guidelines for Traffic & Documentation Job




manual




When copying material provide a link © 2017
contacts
manual-guide.com
search