So, it happened, that you (or someone else) wrote a document. You are about to publish it, but there is an important step to ensure the document's quality – the review. In this article, we will discuss why reviewing is important, how to review your own and someone else’s creations, and how to make the reviewing practice work for you. Before we begin: everything highlighted by the reviewers must be considered as a recommendation. As a technical writer, you own the document, and you bear the main responsibility for its quality. However, use common sense – if a professional highlights a problem in their competence and you are not sure, the best option is to double-check. Never ignore issues highlighted by the relevant professionals. In the first part, we will discuss why reviewing documents is important and what we should review. Why Should You Review the Documents? We review the documents: First, to make sure that the document has the proper quality.
Second, to assess if the document fills the gap and fulfills its purpose.
Third, to perfect writing skills.
Fourth, share the responsibility with people responsible for different aspects of the document. Your document must be a source of truth, both for internal and external use. This is the most important thing about technical documentation. For this, your document should be reviewed. Having your document reviewed does not mean you are bad at writing or understanding the technology. It is a first user experience test: you can make sure you conveyed the technical aspect correctly and see if your document is understandable, easy to use, or does not contain any mistakes. What to Review? To ensure that readers access reliable information, ideally, each document should be reviewed at least by a technical professional: product owner, developer, or quality assurance specialist working on this project. As a technical writer (even the best one) you cannot take responsibility for technical details: it can happen, that important details were missing in the information provided to create this document, or the product has changed since then. The wrong or missing technical information will prevent the document from being the source of truth. On the other hand, poorly drawn diagrams and grammatical errors will impact the user experience. There are several basic aspects to review, each of them (ideally!) should be performed by the respective professional: Technical correctness: the reviewer verifies whether the technical details, algorithms, or examples are correct and understandable. The words used are relevant and match the vocabulary of the reader. This must be done by not less than one technical professional: product owner, developer, or quality assurance specialist from that project.


Text quality: the reviewer checks for style and linguistic errors (and compliance with the style guide). This can be done by any other technical writer, on your own, or using special software.


Usability: the reviewer verifies whether the document is easy to use. This can be done by any junior professional or any person unfamiliar with the task.


Appearance: this can be checked by the designer (for important client-facing documents), UI writer (for documents integrated in UI), or junior professional familiar with design. More aspects can be reviewed if required by your specific case. You have to match the benefit of the deep and detailed review with a more dedicated professional with the goal of the document. Apart from technical correctness, which must be maintained, you can assess whether you need to maintain a good appearance for internal documents or you can skip this for a while. You can use the following recommendation: if the internal document will be used by more than three people for more than a month with little updates, put more effort and conduct a more detailed review. For client-facing documents, put maximum effort into the review. In the next part of the article, we will discuss how to review the documents and how to use the results. So, it happened, that you (or someone else) wrote a document. You are about to publish it, but there is an important step to ensure the document's quality – the review. In this article, we will discuss why reviewing is important, how to review your own and someone else’s creations, and how to make the reviewing practice work for you. Before we begin: everything highlighted by the reviewers must be considered as a recommendation. As a technical writer, you own the document, and you bear the main responsibility for its quality. However, use common sense – if a professional highlights a problem in their competence and you are not sure, the best option is to double-check. Never ignore issues highlighted by the relevant professionals. In the first part, we will discuss why reviewing documents is important and what we should review. Why Should You Review the Documents? We review the documents: First, to make sure that the document has the proper quality. Second, to assess if the document fills the gap and fulfills its purpose. Third, to perfect writing skills. Fourth, share the responsibility with people responsible for different aspects of the document. First, to make sure that the document has the proper quality. Second, to assess if the document fills the gap and fulfills its purpose. Third, to perfect writing skills. Fourth, share the responsibility with people responsible for different aspects of the document. Your document must be a source of truth, both for internal and external use. This is the most important thing about technical documentation. For this, your document should be reviewed. Having your document reviewed does not mean you are bad at writing or understanding the technology. It is a first user experience test: you can make sure you conveyed the technical aspect correctly and see if your document is understandable, easy to use, or does not contain any mistakes. What to Review? To ensure that readers access reliable information, ideally, each document should be reviewed at least by a technical professional: product owner, developer, or quality assurance specialist working on this project. As a technical writer (even the best one) you cannot take responsibility for technical details: it can happen, that important details were missing in the information provided to create this document, or the product has changed since then. The wrong or missing technical information will prevent the document from being the source of truth. On the other hand, poorly drawn diagrams and grammatical errors will impact the user experience. There are several basic aspects to review, each of them (ideally!) should be performed by the respective professional: Technical correctness: the reviewer verifies whether the technical details, algorithms, or examples are correct and understandable. The words used are relevant and match the vocabulary of the reader. This must be done by not less than one technical professional: product owner, developer, or quality assurance specialist from that project. Text quality: the reviewer checks for style and linguistic errors (and compliance with the style guide). This can be done by any other technical writer, on your own, or using special software. Usability: the reviewer verifies whether the document is easy to use. This can be done by any junior professional or any person unfamiliar with the task. Appearance: this can be checked by the designer (for important client-facing documents), UI writer (for documents integrated in UI), or junior professional familiar with design. Technical correctness: the reviewer verifies whether the technical details, algorithms, or examples are correct and understandable. The words used are relevant and match the vocabulary of the reader. This must be done by not less than one technical professional: product owner, developer, or quality assurance specialist from that project. Technical correctness: the reviewer verifies whether the technical details, algorithms, or examples are correct and understandable. The words used are relevant and match the vocabulary of the reader. This must be done by not less than one technical professional: product owner, developer, or quality assurance specialist from that project. Text quality: the reviewer checks for style and linguistic errors (and compliance with the style guide). This can be done by any other technical writer, on your own, or using special software. Text quality: the reviewer checks for style and linguistic errors (and compliance with the style guide). This can be done by any other technical writer, on your own, or using special software. Usability: the reviewer verifies whether the document is easy to use. This can be done by any junior professional or any person unfamiliar with the task. Usability: the reviewer verifies whether the document is easy to use. This can be done by any junior professional or any person unfamiliar with the task. Appearance: this can be checked by the designer (for important client-facing documents), UI writer (for documents integrated in UI), or junior professional familiar with design. Appearance: this can be checked by the designer (for important client-facing documents), UI writer (for documents integrated in UI), or junior professional familiar with design. More aspects can be reviewed if required by your specific case. You have to match the benefit of the deep and detailed review with a more dedicated professional with the goal of the document. Apart from technical correctness, which must be maintained, you can assess whether you need to maintain a good appearance for internal documents or you can skip this for a while. You can use the following recommendation: if the internal document will be used by more than three people for more than a month with little updates, put more effort and conduct a more detailed review. For client-facing documents, put maximum effort into the review. three month In the next part of the article, we will discuss how to review the documents and how to use the results.

Reviewing Documents Part 2: How to Review and What to Do With the Results

How to Onboard a New Technical Writer

Read My Stories

Too Long; Didn't Read

Boost your HackerNoon story @ $159.99! 🚀

Reviewing Documents Part 1: Why and What to Review

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

How to Onboard a New Technical Writer

Reviewing Documents Part 2: How to Review and What to Do With the Results

5 Software Documentation Tools That Make Managing Technical Documentation Easier

'Archbee is Built Out of Frustration with Available Tools': Startup Interview with Dragos Bulugean

Beware of Documentation Management. A Techlead's Hell Loop.

How to Onboard a New Technical Writer

Reviewing Documents Part 2: How to Review and What to Do With the Results

5 Software Documentation Tools That Make Managing Technical Documentation Easier

'Archbee is Built Out of Frustration with Available Tools': Startup Interview with Dragos Bulugean

Beware of Documentation Management. A Techlead's Hell Loop.

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps