Mastering feedback during documentation review
Handling any potential difficulties or misunderstandings that may arise when communicating with the team lead or developers. Scenario where the team lead or developers may not understand certain elements of yourinstructions. How to clarify these points for them?
Review process involves seeking feedback from team members whose primary job isn’t documentation. They may write intuitively as they think to summarize a component or a process with its logical flow of steps. These small misunderstandings may result in confusing team members when the documentation isn’t written entirely from their perspective.
Below is course of action that may help reviewers to align to the document’s intended vision:
Refer to the agreed guidelines and standards; e.g., style guide, checklists, best practices. Ask the reviewers with eagerness, in which way the document conflicts with these.
- Point out who the audience or consumers of the documentation is. It may not be convenient to become too technical if the final audience are end-users, or on the contrary, some technical personnel may find the information too basic.
Set boundaries to your writing style, without disregarding the received feedback. Sometimes it is best to exert some creative control to maintain a consistent tone and a compact document’s length.
If documentation requires additional resources, request whatever URLs or materials are missing. Include them in an appropriate section.
Ask the reviewers if —strictly looking at the documentation— they would still be able to carry out the instructions to an end or make the process work as intended, despite the unclear pieces of information. If they’re still unable to, consider rewriting.
- During review, pay attention to the nouns and verbs, sometimes a keyword can impact drastically the connotation. Technical keywords encapsulate a whole meaning that can make a difference:
request makes more sense in web or API environments rather than query which is used for databases; component may be used to illustrate containerised apps instead of modules that brings design to mind.
pay extra attention to describe pop-up or returned messages, not all of them are errors, they may be exceptions or prompts
in a software context it’s better to use validations (automated checks ) instead of verification which denotes acceptance of deliverables (finished product)
Remember
