Documentation Plan: Be in line with product development
Image courtesy of renjith krishnan / FreeDigitalPhotos.net
The first step in software development life cycle is planning, independent on the development methodology. It is important to plan what features will be implemented, although changes might appear on the way; planning helps companies analyze and take proper actions at the end of the life cycle. Planning is also a trend in technical documentation. As software and products are delivered and marketed with documentation, planning documentation is actually a normal thing to do and it is in trend with the software / product it accompanies.
The purpose of a documentation plan is to align expectations of Product Managers and of managers in charge with delivering software / products. Documentation plan also provides a brief description of the product new features and improvements to the technical writers in charge of creation and update of documentation.
It is recommended to create the documentation plan during the software / product planning phase.
Documentation planning might be different from a company to another. If the company has a technical writing department composed by at least two technical writers, than the Technical Writer lead should create a documentation plan, addressing aspects like: audience, requirements for the technical writers, risks and challenges, resource allocation, key contacts for technical writers, deliverable list and documentation schedule.
This content template suggests what a documentation plan should contains in order to cover all needed information that helps technical writers have a clear view on updates to be done during the software development lifecycle together with designated Subject Matter Experts (SMEs) who will provide input and clarifications when needed.
A documentation plan should cover topics like:
- Introduction. A short introduction on the products to be documented. It also provides an high-level overview of the As Is solution features.
- Deliverable. It is highly important to have a clear view of all documentation output: User’s Guide, Administrator’s Guide, tool-tips, context-sensitive help and other. This section should contain the complete list of documentation deliverable. Although not every piece of information might be affected by new product features, it will help you keep a real-time track of what has changed and what remained unchanged. You could update the documentation plan at a latter time in the development life-cycle if managers decide to implement / improve functionality which was not planned in the initial product planning phase.
- Localization. If you deliver documentation in many languages, list the product documentation and languages in which your documents are translated into. It does not matter whether the localization is done internally by you or by outsourced translators; in some companies it is the writers’ duty to check localized content against initial documentation. If this does not apply to your organization, remove this section.
- Target Audience. Knowing the target audience helps technical writers writing their language. Use this section to describe who the target audience is and the required skills for each type of user (if the product addresses multiple types of users).
- Requirements. List all he resources needed for the technical writer to complete the tasks (mention both hardware and software requirements). If the writer should have specific technical skills, mention them here.
- Timeline. Discuss with product managers and plan deadlines for various phases of documentation. Provide a brief description of the products’ road map.
- Assignments. This is the traceability matrix of assignments, where the documentation manager assigns tasks to each writer.
- Reviewers. List all people in charge with documentation review.
In another post we will post for download a template which might help you create the documentation plan that you need.