Technical Writing, User Guides

How to Write Your First Technical Documentation Plan

Posted on by Anthony James
API documentation template
09
Apr

Use the following guidelines to plan, schedule, and writer the user and support technical documentation for your next software product.

Examples of this documentation include user guides, admin manuals, online help, and release notes. 

Preparing a Documentation Plan involves several different activities. Let’s examine what’s involved.

Work Breakdown Structure Template

[Learn more about this template here]

Depending on the complexity of the project you may want to change the depth of the plan, but most plans will include:

  1. Overview
  2. Resource Requirements
  3. Schedule
  4. Deliverables

Tip: Documentation plans are also known as Information Development plans.

In this article, we’ll look at Resource Requirements and Scheduling.

Creating a documentation plan involves scoping resource requirements and scheduling the individuals involved in information development activities.

Before you get into the actual planning, some things to consider are:

  • Can the existing documentation set be reused?
  • Does it require updating or revising?
  • Have the current tech writers worked on the previous doc set?
  • Do you need to hire and train new writers?
  • Do you have a budget / daily rate for these writers?
  • Is the solution you’re planning to document ready?
  • If not, is it sensible to start documentation?

Deliverables

List the deliverables that you will provide. Highlight if any of these are critical and/or mandatory for the solution’s delivery.

You may want to expand on these and describe the document format (Word, PDF, HTML), estimate page count, estimate graphic requirements.

Estimating Costs

When estimating the associated costs for this project, consider the following factors:

  • Who is responsible for non-writing tasks, for example, translation, production, circulation etc.
  • Will Subject Matter Experts and Users need to be interviewed? If so, when and where? Are there additional costs in performing these activities, e.g. travel expense?
  • Will tech writers need to attend training sessions and/or workshop in order to understand the software?

Identifying Resources Requirement

To plan successfully, you will need to capture all resources that will be required throughout the project lifecycle. At first glance, most of us think of the human resources required. That’s the writers, editors and programmers.

But you also need to work out what software, hardware, security, passwords, and other resources you may need.

First up, identify all individuals involved in producing the document, not just those involved in writing activities.

  • Graphic Designers
  • Human Interface Designer
  • Information Architects
  • Product Manager
  • Programmers
  • Software Manager
  • Technical Editors
  • Testers
  • Web Designers

Identify how many person months from the [start date] to [end date] are required for the project. This helps estimate costs involved in producing the documents, especially if you need to localize material

Hardware

Identify the hardware requirements, for example, access to servers with sufficient memory and disk storage for running Adobe FrameMaker, Visio and DITA authoring tools simultaneously.

You may also need access to servers to test and verify your documents.

Software

Identify the software required for content development:

  • Adobe Acrobat
  • Adobe FrameMaker
  • Adobe PhotoShop
  • Camtasia SnagIt
  • Madcap Flare
  • Microsoft Visio
  • Microsoft Word

Writer’s requirements

Describe the writer’s requirements, for example:

  • Access to documentation and specifications
  • Access to test system for verification
  • Access to subject matter experts

Project Scheduling

Outline the project’s goals and reporting structure. After this, identify your assumptions and dependencies.

If these are NOT met, the project is at risk and unlikely to meet its objectives.

Assumptions

Examples of assumptions for an IT project include:

  • Changes to schedules will effect the delivery dates
  • Changes to resources will impact the quality of products as new hires will have to be skilled up
  • Changes to specifications will mean that content will have to be reevaluated and adjusted accordingly.
  • Reviewers will be available and provide feedback on schedule.

Dependencies

  • Examples of dependencies for an IT project include:
  • Availability of Subject Matter Experts
  • Availability of system, network access, password, physical access to buildings if required, access rights
  • Access to specifications, project plan, test scripts as required
  • Review and feedback is received on time

Documentation Plan Template (MS Word/Excel WBS)

Your Documentation Plan template describes how your technical documents will be prepared, delivered and distributed. This is also known as an Information Development (ID) Plan. Essentially, it serves as a project plan for the documentation requirements on a software project.

[Learn more about this template here]

Use this template to:

  • Identify the content, format, page count, size etc for each document in your next publication cycle
  • Prepare cost estimates for project duration and schedule resources to meet the documentation requirements
  • Have greater control over your budget and ensure that risks and issues are addressed before starting the writing phase
  • Identify the necessary tools/licenses/PC configuration and ensure documents are scoped correctly with the appropriate level of detail

Editor’s Note: This post was originally published in October 2007 and has been updated for freshness, quality, and comprehensiveness.

Anthony James