What is a software documentation plan? This is a project plan for the technical documents you plan to write for the next software release. Like a standard project plan it captures the resources, requirements, costs, and deliverables.
As this is for technical writers, the documentation plan will focus on the content you intent to deliver; it may include the document format, estimated page count, delivery format and other such items.
Software Documentation Plan
In general, your documentation plan (also called Information Development Plan) will include the following sections:
- Introduction
- Data Management
- Guidelines and Requirements
- Schedule and Cost Estimates
- Formatting
- Standards
- Submission Policies
Documentation Plan: Introduction
To start the document plan, outline the purpose, scope and objectives. You must also describe the information to be created (e.g. user guide, online help, and release notes) and how you will store, manage, share and publish the documents.
The other major part of the document focuses on who will help develop the documents (i.e. technical writers, graphic designers, usability experts, testers etc) and also guidelines on the style, format, security and sharing of the files once completed.
Include the following in this chapter:
- Overview
- Purpose
- Scope
- Objectives
Data Management
Next, we look at how the technical documents will be managed across different systems, platforms and sites. In this chapter outline how you will:
- Capture
- Manage
- Distribute and
- Archive project information
To reduce data contamination, set guidelines on how project and product information will be managed effectively.
Project information includes all documentation that supports operations, such as:
- Reviews
- Technical analyses
- Design information
- Technical papers
Include the following in this chapter:
- Requirements for Information Management
- Information Management facilities
- Website
- Intranet
- Technical Library
- Controlled Documentation Lists
- Physical Repository
Documentation Guidelines
Once we have the data management in place, outline the requirements for project documentation and how you plan to prepare and control documents and records.
Include the following in this chapter:
- Preparing Controlled Documents
- Review and Approval
- Public Release of Documents
Time and Production Cost Estimates
This is one of the critical parts of the documentation plan. Your cost projections impacts how you’re funded, issues if you go over schedule, and dependencies on other business units, for example, if they will be charging you for services.
To do this, estimate the amount of time (i.e. total number of hours/days) it will take to complete the documentation task. When estimating the total cost, consider whether the technical documentation exists, requires updating, needs revising or must be developed from scratch.
To do this correctly, make sure you include costs for:
- Interviewing subject matter experts, users, and customers
- Attending and organizing training sessions
- Writing
- Editing
- Production
- Additional software licenses if necessary
Include the following in this chapter:
- Dependencies
- Document Formats
- Final Document(s)
- Printing, Packaging, and Distribution
- Production Estimate
- Production Requirements
- Review Process
- Reviewers
- Schedule
- Time Estimate
- Writing Strategies
Formatting
Most companies use style guides and branding guidelines to control the look and feel of the document. In this chapter, describe the formatting requirements for the technical documentation.
This also reduces any ambiguity or assumptions by the technical writing team on how the documents should be formatted. The information development plan becomes their bible.
Include the following in this chapter:
- Appendix Format
- Bullet Formatting
- Code Formatting
- General Formatting
- Glossary Format
- Graph, Chart, and Screen Capture
- Header/Footer Format
- Heading Formatting
- Table of Contents Format
- Title Page Format
Standards
After you’ve described the formatting guidelines, discuss the writing standards that all technical writers must follow when creating documents.
Highlight that writers must adhere to these standards.
This ensures that the documents are delivered to the correct standard and support the company’s Quality Plan.
Include the following standards in this chapter:
- General Documentation Standards
- Quality Measurements for Deliverables Submitted
- Standards for Software Development
- Standards for Design Team
- Standards for Software Testing Team
Submission Policies
In the final chapter, describe how documents must be submitted for review and approval.
Technical Writers must submit all deliverables according to guidelines in the Quality Assurance Plan.
Include the following in this chapter:
- Review Submission
- Final Submission
Conclusion
These are the main sections required for a software documentation plan. If necessary, you can drill down and add more information for different sections. It really depends on the size of the project and how much documentation is required. Pay special attention to the costs section and give yourself some leeway for scope creep.
Over to you.
What mistakes do Technical Writers make when writing software documentation plans? What’s the most important chapter to get right?