Sample Documentation Plan (PDF, DocBook XML, Microsoft Word (.doc))
An excerpt from Richard L. Hamilton’s Managing Writers: A Real World Guide to Managing Technical Documentation.
You are free to distribute and use this template, provided you do not charge for distribution or use.
I have tried to make the written plan as concise as possible. As I have written plans over the years, I keep coming back to the information included here, and rarely find a need for additional sections. If you need other sections, by all means add them, but consider what you really need and avoid fluff.
You can use the template on a per deliverable basis or on a per project basis. Unless the project is very large, I would suggest you use the latter. This will minimize repetition of project-related information and limit the number of documents you need to maintain. If you have a large project, you may also want to consider writing an umbrella document that contains the Executive Overview, Objectives, Overview of Deliverables, Assumptions, and Resources, then using sub-documents for the remaining sections.
Here are some terms used in the template. The term product refers to the product, service, or project the documentation is being written for. The term client refers to the organization the documentation is being written on behalf of, in other words, the organization paying for your work. The term user refers to the end user or customer of the product and its documentation.
This section summarizes the plan, identifying the high-level deliverables, broad schedule, and level of resources to be used. Its purpose is to reassure the client that you understand what you are going to do, when you are going to do it, and what it is going to cost.
This section describes the project and identifies the objectives. It also puts limits on the objectives by defining what will not be covered.
Describes the type of documentation proposed for this project and identifies the specific deliverables.
Describes the schedule from the client’s perspective. This should include the following milestones for each deliverable:
Design review: A review of the deliverable design by the client. Some clients will not want to review the design, but I suggest you include it as a milestone and push hard for them to participate. An early review will almost always save trouble later on.
Draft reviews: There will be at least one, and possibly more interim reviews of each deliverable. There may also be separate reviews of different parts. With modular methodologies, there will need to be reviews of each module.
I recommend scheduling one draft review, with an option for a second review if there are significant problems with the initial draft. If the initial review comments are clear and unambiguous, you should be able to skip a second draft review and go right to the final review.
Final review: This is a review of what should be the final version of each deliverable.
Sign off: This is the sign off by the client that the deliverable is acceptable for publication.
Deliverable to production: The date the deliverable is sent from the documentation team to whoever will produce the final product. There may be multiple dates if you are single sourcing.
Deliverable published for users: The date the deliverable is first in the hands of a user (not counting possible user reviews).
Dependencies: This includes milestones for deliveries to your team or other dependencies. While the previous milestones are roughly in chronological order, dependencies should be interspersed as appropriate.
Depending on your process, you may be able to combine some of the milestones above. For example, if you publish directly to the Internet, the last two dates might be the same. Or, the sign off date might be the same as the date you send the deliverable to production, if that part of the production is automated.
General assumptions that do not have an associated milestone, carry a risk, or need a contingency plan are identified here. These are assumptions like, “We will use XYZ corporation to manufacture printed manuals.” Only identify assumptions here if they will be useful to readers or if they identify something that is different from the norm.
Assumptions that have a milestone, carry a risk, or need a contingency plan are handled here as risks. Risks are documented by stating the assumption at risk, the risk itself, the likelihood of it occurring, the impact if it occurs, and your contingency plan. Each risk is documented using the following format:
Statement of the assumption that is at risk.
What the risk is. For example, “prototype is not ready.”
How likely it is that the risk will occur. This can be expressed as “low, medium, or high,” or as a percentage.
The impact of the risk occurring. This should include both an assessment of the magnitude of the impact (low, medium, or high) along with a description of the specific impact. For example, “If the prototype is not ready by date X, documentation development will have to pause.”
The plan for handling this risk if it occurs. This should include the actions that will be taken and the costs of those actions.
Describes the resources required to create your deliverables. Depending on what the client wants, this could be expressed in terms of staff months, dollars, or a combination of the two. You may also need to break this down into the kinds of resources required, which may include: a manager, writers, editors, graphic designers, and indexers. You can also identify any special skills or experience required for any position.
Resources might also include expenses for equipment, office space, materials, contract services, consultants, software, IT services, printing, web publishing, and so forth.
Here is where you collect signatures or other means of approval from representatives of your client. You may not need to or be able to get every signature on paper in ink, but you do need to obtain and publicly record approvals from all stakeholders and anyone you are depending on.
Copyright © 2009 Richard L. Hamilton