The accuracy of your organization’s technical documentation benefits your company and customers by offering a credible resource for how to use your product. Inaccurate and outdated documentation can hobble internal development efforts, and negatively affect external customers as well, when they cannot resolve their own issues by consulting the documentation that accompanies your product. Your company’s credibility is also damaged, because the customer develops doubts about the product, thanks to the inaccuracies encountered in the documentation.
A lack of accurate and accessible information also increases the learning curve for new developers and other technical staff. Here are some tips to help improve the technical accuracy of the documentation produced by your development team:
Tip 1: Develop a technical review checklist
Many developers and managers lack experience in how to technically review a document. Here are some points to include in a review checklist to keep the reviewers on track and focused on the technical accuracy of the documentation:
- Focus on the technical facts to verify that the technology works as documented. A technical review is not an editorial review.
- Verify the technical accuracy of all procedural steps included in the document.
- Verify the technical accuracy of all screen captures in the document.
Tip 2: Build accountability into the document review process
One of the reasons technical reviews are often disregarded is because no accountability is built into project plans for technical reviews. Strategies for building accountability into technical documentation reviews include:
- Add the name of the author(s) and technical reviewer(s) to the documentation. Some companies have a policy against naming staff, but including author and reviewer names promotes communication with internal staff. For external audiences, such as user guides for commercial, off-the-shelf software, including the author and reviewer names recognizes the contributions of the development team.
- Make technical reviews of documentation part of the annual review process for developers.
- Assign technical reviewers for documentation in the project plan.
Tip 3: Raise the accuracy bar for technical writers
While the job title technical writer is subjective in many organizations, the persons in these positions must have a stake in the technical accuracy of the documentation they develop, since it is their primary task.
Managers should set the appropriate technical accuracy level that writers are expected to maintain. While some technical writers may balk at increased expectations about their understanding of the technology, increasing their stake in the project is a win for everybody. If the writers are not able to meet the higher standards, you may need to review the role of your technical writers as compared with your corporate strategy and client requirements.
To assist technical writers, you need to level the playing field by enabling writers to dig deeper into the technology: Managers should:
- Involve the technical writers in design and development meetings about the product.
- Involve technical writers in the development of technical requirements, functional specifications, and design documents.
- Include technical writers on any development group mailing lists.
- Provide access to internal releases of the product during the documentation development cycle. It can be easy to become cloistered as a technical writer and rely only on interviewing the experts, but enabling them to become “hands-on” with the product can provide a new perspective that developers and project managers may not be able to see for themselves.
- Encourage the technical writers to read more about the technologies behind your products. For example, if you develop Java-based applications, encourage the technical writers to become more fluent in the Java programming language.
Tip 4: Set priorities for busy, but key, developers
There always seems to be the “alpha wolf” developer that holds a lot of information in his head about the project but is involved with multiple projects. Even though his or her schedule is tight, the product knowledge held by this developer is necessary to ensure accuracy in the documentation.
While many of us have to do more with fewer resources these days, these developers were spread thin even when times were good, due to their exemplary knowledge and work ethic. Here are some tips on how to manage the documentation review you need from these busy developers and ensure their knowledge benefits the documentation:
- Forget about having them review the documentation from cover to cover.
- Work with the document authors to identify the sections of the document that absolutely must be reviewed by this person.
- Work with them and their management to obtain some uninterrupted blocks of time to review the document.
- Provide the reviewer who has a stretched schedule with a list of exactly what you need them to review in the document. Assure them that other team members are reviewing the rest of the document, and their review input is absolutely necessary for the sections that relate to their direct area of technical expertise.
Building the better technical review
A thorough technical documentation review benefits both external and internal customers. While some technical staff consider conducting these reviews a chore, managers face the challenge of setting priorities to enable a thorough review process while maintaining critical development efforts.