Category: Technical Documentation
Last updated on Jan 10, 2023
When you’re working on a project and have to conduct a documentation review, you might be confused about what exactly this process involves, who are the stakeholders, and the what the outcome of the review process might be. In this blog piece let us scratch the surface of the Document review process and its vitality to quality content.
Documentation review is a process where the document goes through one or multiple stages of review and reviewers and the feedback gets amended in the document. The outcome of the document review process is that it enhances the accuracy and quality of the document.
Documentation review is one of the most time-consuming activities regarding end-user documentation. It requires much concentration and focuses since it’s not as simple as reading through the document and spotting grammatical errors or typos.
In fact, it’s much more complicated than that and requires scrutiny of every word, heading, sentence, and paragraph to ensure that there are no logical inconsistencies or gaps in information. You need to understand the structure of the document, identify the primary audience, evaluate its readability, identify any truncated sentences or sections that should be expanded, etc.
– The document is reviewed by a relevant to the core content of the document
– The document is reviewed by a senior writer, or an editor reviews the document’s for overall quality
– The document is reviewed by the Subject matter expert or the end users
– In case the document has to adhere to regulations and compliances set either by the industry, governing body, or the company the document is put through this review as well.
When you’re conducting a documentation review, the first thing you need to do is determine or understand the purpose of the review. This will determine the criteria you use to evaluate the document during the review and the length of the review.
For example, suppose you’re conducting a review of an internal employee training document. In that case, your primary goal will be to ensure that the document is accurate and that the information is presented in a way that’s both easy to understand and accessible to the employee. The outcome of the document should be that the employee is well-informed of the context after reading the document.
On the other hand, if you’re conducting a user manual review, your primary goal will be to ensure that the document conveys accurate, complete, and consistent information about the product or service to the end user.
For example, Let’s assume you are working on a user manual for an HR portal. You are reviewing an article on how users can reset their login password. In that case, you need to ensure the article contains the complete application process flow leading up to the Login screen, reset password button, and what happens after you have initiated the reset. Also, you must ensure the consistency of the business terms in the article.
Document review is done mostly by multiple reviewers and sometimes by a sole reviewer. The reviewers can be both in-house or independently hired reviewers. As far as personnel is concerned in the document review they can be other writers, Subject matter experts (SME), Editors, SEO personnel, or anyone relevant to the document for that matter.
A Subject Matter Expert (SME) can be anybody from your Developer, Engineer, Support manager, Analyst, etc., who has a comprehensive understanding of the core concept of your document.
For example, In a SaaS company, the developer can be considered a Subject matter expert as they develop the feature that the technical writer documents.
The role of the SME in the review process is crucial as they scope out all the technical gaps and inconsistencies in the document. It is not always the case that the document writer would be an expert on the technicalities of a feature compared to technical personnel working on the same product. Hence, Subject matter experts and Technical writers should work hand-in-hand on technical documents or product documentation.
When conducting a documentation review, you need to look for several things, including the quality of the writing, the structure of the document, the context provided, the flow of content, and the readability level of the document.
Let’s discuss these aspects in detail.
Quality of the writing – Whether you’re reviewing a user manual or training documentation, the quality of the writing is the first thing to look for when conducting a review. You must ensure that the document is free of grammar, punctuation, and spelling errors. If the document is riddled with these kinds of errors, it will reflect poorly on your organization, especially if it is an end-user document meant for customers. One suggestion to aid you with the review is enforcing a custom or available Document style guide. You can also use third-party grammar check tools such as Grammarly to a certain extent.
Structure of the document – The structure of the document refers to how the information has been organized. If the document has a table of contents, you must review the table of contents and make a note of any inconsistencies. If the document does not have a table of contents, you must identify the primary sections and provide a summary of each section. Usage of the Heading tags (H1, H2, H3…) is highly recommended. Also, the document should follow a set document pattern, the most common being Introduction-Problem Statement-Resolution-Conclusion-References.
For example, Document360 editors (Markdown and WYSIWYG) lets you add Heading tags such as H2, H3, and H4 in your article. The platform also has the ability to autogenerate Table of Contents (TOC) based on the Heading tags provided in the article.
Absolute information – You must also look for the amount of information provided in the document during the review. All relevant and necessary areas, explanations, and context should be covered with ample examples and visual representations (If relevant).
For example, in a product comparison document, a table explaining the differences between various products in the ERP platform should have enough detail to make the reader understand the differences and get insight into each product’s unique selling proposition (USP).
Flow of sentences – You also need to look for the flow of sentences. In other words, you need to ensure that each sentence flows easily into the next one and that there are no abrupt or truncated sentences. If a sentence ends abruptly in the middle of a thought, this will confuse the reader. At the same time, you also have to be cautious to keep your sentences concise and complete at the same time.
Readability level of the document – You also need to look for the readability level of the document. This means that you need to evaluate the document according to the Flesch Reading Ease score. The lower the score, the more difficult the document is to read. Many CMS (Content management system) platforms provide an option or integration to measure the document’s readability.
For example, Document360 provides a Health check metric feature where authors can get insights on an article’s SEO health and Readability metrics. This feature assesses metrics such as Sentence/paragraph length, sub-heading distribution, and Readability score.
Also Read: Tips to keep a healthy knowledge base
Schedule a demo with one of our experts to take a deeper dive into Document360Book A Demo
When conducting a documentation review, you must also decide whether to run a peer review. In other words, you must choose whether to have independent or internal team reviewers proof the documentation.
It would be best if you considered several factors when deciding whether to run a peer review, including the nature of the documentation, size, and importance.
If the documentation is extremely important, it would be worthwhile to spend the extra money to hire an independent reviewer. You can also decide to go in for in-house peer reviews for different aspects of the document.
If you decide to hire an independent reviewer to conduct a peer review of your documentation, you must do so fairly and transparently. You must provide detailed instructions about what needs to be reviewed and what should be done during the review process. You can also provide feedback from previous reviews to give the reviewer a clear idea of what needs to be done during the review process.
Before you hire the reviewer, you must have a clear understanding of the deliverables from the reviewer. You must also agree to the terms and the timeline for review completion. It would be best if you also were transparent about the purpose of the review and the criteria used to evaluate the review.
If you decide to run an in-house or internal review, you can apply similar criteria, but you can add multiple levels of review and include multiple personnel if required. This will reflect in the review being optimal and guarantee you high-quality documentation.
At Document360, all our documentation goes through 5 levels of peer review before publication.
We use the ‘Workflow‘ feature in the Document360 product to help us manage the peer review process. This allows us to add multiple levels of review, assign reviewers, record feedback, set due dates, and track revisions. The different phases of the review can also be custom set by the Document360 project owner or admin.
Want to find out how Document360’s Workflow feature helps to streamline the process? Check out the video below:
Once the article is drafted by the Author/Document writer, they use the assign feature in the ‘Workflow assignment’ option to assign different users accounts in Document360 for each of the review phases.
Additionally, they can also set due dates for each of the review. This will trigger a notification to the assignee/peer reviewer with information about the article name, assigner, and due date.
The peer reviewer then reviews the article for a specific aspect like grammar or technicality. Once the review is complete the peer reviewer can add the comments for the article in the ‘Workflow status’ section or use the ‘Discussions’ board in Article settings.
This helps us maintain a record of the peer reviews the article has undergone and the comments/feedback received from those reviews.
An intuitive technical documentation software to easily add your content and integrate it with any application. Give Document360 a try!GET STARTED
The document review process’s importance is on par with the drafting of the content itself. A new perspective is sometimes what is lacking from specific documents. The document review process ensures that if the document needs to be kept in a style guide’s lane, that also happens. A documentation review is also important because it can help improve the final product’s quality. If the documentation has been reviewed and edited beforehand, there is a lower chance that minor errors will be missed and made into the final product.
Also, taking into account the future of technical documentation and its sustainability, the quality of documents achieved using the document review process is very important. With the penetration of Artificial Intelligence in customer service, such as Voice assistants, quality support documentation can make a whole world of difference when fulfilling customer needs and queries.
The final thought is that the document review process and the framework to facilitate the review are impeccable.