Geetha Haridas, Qualcomm
November 15, 2023
If you’re writing documentation, you need to ensure it’s accurate.
End-user orientation, clear writing, and attractive presentation of content are some of the key attributes of good documents. However, documents are truly worthwhile only when they provide accurate information. Incorrect information serves no purpose and could be detrimental in use.
Writers typically work with technical reviewers to identify errors in documents. The attitude of reviewers towards the documentation function has a deep impact on the quality of reviews and the resulting documentation. Unfortunately, negative perceptions such as ‘who reads documents anyway’ and ‘writers simply make documentation look pretty’ do exist. Therefore, writers often find it hard to make reviews more effective and gain acceptance as an equal contributor towards product development.
Effective reviews require a two-fold effort—setting the right expectations with reviewers and communicating appropriately. This article explores a few issues surrounding technical reviews and offers some hints and tips for defining a review process and working with different types of reviewers.
Involve reviewers early in the process to ensure that discrepancies are identified at an early stage.
Defining the review process
Defining a review process can help you to set the correct expectation with your reviewers and obtain information and feedback throughout the documentation life cycle.
To define a review process, clarify your documentation requirements and milestones, identify your reviewers and involve them early in your documentation lifecycle.
- Create a documentation plan and schedule
Reviewers often ignore documentation reviews when they are under pressure to meet their own deadlines. A documentation schedule can help you to co-ordinate with reviewers to allocate sufficient time for reviews. Even if you work in an environment where consistent processes and procedures do not exist, ensure that you create a documentation plan to help with:
- Identifying the key stages of your documentation lifecycle and the review milestones.
- Clarifying the tasks and effort involved in producing documentation. When you have a formal documentation plan in place, reviewers are likely to appreciate the effort involved in producing documentation and take technical reviews seriously.
- Identify your reviewers
Identify reviewers who understand the importance of your documentation. In addition to working with Engineers, involve Product Managers, Development Managers, and Support Managers, who have a broad view of project-related issues. These personnel can also point you to useful sources of information and notify you about any changes in the scope of the project.
- Involve reviewers early in the process
Involve reviewers early in the process to ensure that discrepancies are identified as soon as possible, for example, when you are creating the outline for your document. When you involve reviewers early in the process, they are also likely to feel accountable for the documentation that you produce.
Working with different types of reviewers
In an ideal world, writers expect reviewers to understand the challenges in producing quality documentation and provide valuable input throughout the documentation cycle. Writers also expect reviewers to proactively share their knowledge and answer queries on demand.
However, to the writers’ disappointment, reviewers often fall into one or more of the following categories.
Hello…Is someone out there?
Reviewers of this type feel that any involvement in the documentation process is a waste of their time. They rarely respond to writers’ queries. Writers usually find it a challenge to establish two-way communication with these reviewers.
- Hints and tips:
- If you primarily communicate by sending emails, then change your communication technique when working with these reviewers. Apart from sending emails, meet these reviewers face to face or schedule meetings.
- Never send emails with trivial questions, as your reviewers are likely to get convinced about not responding to your queries. Instead, consolidate your queries and send them in a single mail.
Everything is fine (always?)
While some reviewers do respond to writers, they always suggest that the content is of excellent quality. However, this might be a risky situation where reviewers might be ignoring the documentation and providing positive feedback to keep writers happy.
- Hints and tips:
- In general, these reviewers do want to respond to you, but probably find it overwhelming to go through the details of the documentation
- Draw the attention of these reviewers to specific issues. Send them a list of questions along with the documentation. To help them to quickly review the essential content, highlight your queries within the document. Continue to ask pertinent questions.
Remember that you are an equal member of the product development team.
Nothing is fine (always again?) and do as I say
This is the nitpicking category of reviewers who believe that writers can never get it right. Reviewers from this category might even pick on editorial issues and question well-established rules of technical writing. While these reviewers do offer feedback during technical reviews, they tend to be possessive about the words they contribute and try to control the final output.
- Hints and tips:
- Reviewers of this type are typically difficult to please and very rarely can you work with them without involving your manager.
- When they point out perceived issues in the documentation, request them to give you precise explanation and justification for their comments. Educate them about your writing guidelines. To avoid the potential problem of rewriting the entire documentation just before a product release, report any issues to your manager early during the process.
Respect your reviewers’ time.
Too many cooks?
When multiple reviewers review a document, writers might find it difficult to co-ordinate with them, either because the reviewers offer contradicting feedback, or refuse to take ownership, which then results in the documentation being ignored.
- Hints and tips:
- Minimize the number of reviewers who are required to review your documentation.
- If you must involve many reviewers, designate one of the reviewers as the primary point of contact who can consolidate review feedback and resolve contradicting review comments.
Some general dos and don’ts
Writers must often use different strategies to work with different types of reviewers. Yet, the attitude of reviewers towards the documentation is also shaped by how writers perceive their own work and carry out their responsibilities. To ensure that you get the support you need:
- Ask for help when required, but do your homework before you start writing, before you ask questions, and before you send documents for review.
- Be confident when you ask for product demonstrations and source information. Remember that you are an equal member of the product development team.
- Escalate issues early in the process. If your reviewers are difficult to work with, get help from your manager.
- Respect your reviewers’ time. Remember that your reviewers have their own deadlines to meet.
- Integrate with the rest of the product development team. Gain the acceptance of your reviewers by making your documentation useful for them, for example, by sharing your documents with new Engineers who want to gain product knowledge.
- Apply your skills to resolve larger issues, for example, give your suggestions to enhance the usability of user interfaces.
- Do not be over accommodative or accept unnecessary criticism from reviewers.
- Avoid over-communication.
Reviewers form an indispensable part of the documentation process, and writers cannot function without reviewers. Writers can help reviewers to understand the importance and impact of documentation reviews. Tools, knowledge, writing skills do enhance the profile of a writer, but writers can produce accurate information only if they know how to work with difficult reviewers. Writers must know their reviewers, demonstrate their capabilities, and build constructive professional relationships. Communicating and responding appropriately is the key to resolve most of the issues.
This article originally appeared in the Communicator journal published by the Institute of Scientific and Technical Communicators (ISTC), UK.