How to create a documentation plan

A documentation plan lays down a blueprint for the whole writing project. As a writer, before you embark on your documentation project, create a proper documentation plan and get it approved by key stakeholders. This will establish your credibility in the event of any crisis. It is important to study the marketing/customer requirements document. Ideally, the requirements document should state clearly the features to be documented, the depth of information to be included in the documentation, and the format (HTML, PDF, Word, etc). The next step should be to study the functional specification.

On the basis of MRD and the functional specs, the documentation plan should include the following details:

• The product name, scope, and purpose

• Milestone dates

• List of documents that will be created and/or updated. If the project is about updating an existing product, list the features to be documented. If the project is about releasing a new product, additional planning is required. There can be multiple deliverable types needed, ranging from a single-paged addendum to a context-sensitive online help system.

• Version control tool for managing the source files, for example, Snapshot CM, Rational ClearCase, git.

• Features that will be documented

• Work estimate and committed schedule for documenting each feature or completing each document

• Committed documentation milestones

• Documentation Reviewers including review schedule. There are 2 ways to conduct a review, collect edits individually from each reviewer or hold a review meeting to review everyone’s comments. Multiple reviews may be required. You can also use Adobe’s Shared review process to collect feedback from multiple reviewers.

• Depending on the program include any training material needed for the launch.

• Risks, assumptions, and dependencies. Include the following: Main risks of the documentation project (e.g. last-minute feature additions), probability of each risk, Impact of each risk, Risk mitigation plan, and Owner of the mitigation plan)

• Doc approval process and approvers

• Documentation delivery and distribution plan.

Main components 

• COVER PAGE summarizing the name of the project; organization, and copyright or confidentiality statements.

• Table of Contents – Proposed chapters and their tentative content.

• An introduction that covers the purpose and scope of the plan.

• HISTORY (or REVISION LOG) showing the revisions the plan went through, with dates, the names, and titles of the persons who wrote different versions.

• RISK FACTORS – What are the dependencies to complete the documentation? Which critical factors may bring this project to a halt? What are the impact (H/M/L) and the probability (H/M/L)? What measures should be taken for such an eventuality and who are the mitigation owners.

• Reviewers and Review Process displays the names, titles, and contact information of the writer and all stakeholders involved with the documentation project.

• Product features – what are the features that will be documented.

• Document specs – Is this going to be an online document, a printed document, or both? Will it be single-sourced? Will the project be using a client template? Which version control tool will be used for managing the documentation source files.

• Schedule – What are the milestones in the development of the document? What is the effort required? When should the review cycle(s) be finished? How many rounds of reviews should be allowed? What is the start/end date for the whole project?

Kickstart every technical writing project with a well-crafted and approved plan. 

9 steps to create Technical Documentation

1. Read the Marketing Requirements Document (MRD) and functional specification. The MRD should list out clearly the documentation requirements.
2. On the basis of MRD and functional specs, create a documentation plan that includes
•  Product name, scope, and purpose
• Milestone dates 
• List of documents that will be created and/or updated. If the project is about updating an existing product, list the features to be documented. If the project is about releasing a new product, additional planning is required. There are multiple customer documentation deliverable types a project could require, ranging from a single-paged addendum to a context-sensitive online help system.  
• Features that will be documented
• Work estimate and committed schedule for documenting each feature or completing each document 
• Committed documentation milestones
• Documentation Reviewers including review schedule. There are 2 ways to conduct a review, collect edits individually from each reviewer or hold a review meeting to review everyone's comments. Multiple reviews may be required. You can also use Adobe's Shared review process to collect feedbacks from multiple reviewers.
• Depending on the program, include any training material needed for the Launch.
• Risks, assumptions, and dependencies. Include the following: Main risks of the documentation project (e.g. last minute feature additions), probability of each risk, Impact of each risk, Risk mitigation plan, Owner of the mitigation plan)
• Affected BOMs and/or document numbers
•  Doc approval process and approvers (outside the tech pubs team)
• Documentation delivery and distribution plan.
Distribute the plan to the core team members: PLM (Marketing), R&D lead (Engineering),  and PM (Program Manager) who will review and approve the plan.
After the approval, create the draft document by attending the core team meetings, interacting with the application, studying design documents, asking questions to the testers/developers.
Send the draft to the reviewers identified in the documentation plan.
Update the documents as per the review comments, address all the major and critical documentation CRs and defects identified during the documentation validation.
Obtain the documentation approval from the designated reviewers/approvers.
Generate the final version.
Check in the final document into the build branch.