Cross Review: Why It Is Needed And Why It Will Make Your Documentation The Real Deal

A little introduction should never go amiss. I am Alina and I manage a team of technical writers in a fintech company. Our job is to create documentation for internal use. Developers, product managers/owners, QA, and analysts are our main customers.

Photo by John Schnobrich on Unsplash

There are different types of technical documentation, with the most common being, of course, external and internal ones. External documentation in its majority is meant for end-users, if we are talking about product development. Internal documentation is aimed for the employees of the company. It is under a non-disclosure agreement (NDA), and is dedicated to making the communication between teams more efficient.

Internal documentation is usually based on a “good enough” principle, which is quite risky to adapt and not to get carried away with. At some point, you might start neglecting mistakes, which make documents hard to digest. For example, such documents may lack crucial details, leaving readers with unanswered questions and potentially causing frustration. Also, the documentation that is initially “good enough” may become difficult to update and expand in the future, especially if the structure is not well-thought-out.

To find a balance in this situation, we have adapted a new practice of cross reviewing documents within the team. The cross review is designed to check the documents of your fellow technical writers. Each of the reviewers has a right to leave comments on the presented article, add suggestions, spot grammatical and stylistic errors. Reviewers can also provide an overall feedback on the document if necessary. For example, if the article appears fine, but does not necessarily correspond to the given task.

Why it is Important

Self-proofreading may not always be the most efficient method for reviewing your work. Familiarity with the material can cause you to overlook mistakes and stylistic inconsistencies that might not be obvious. An objective review by a fresh, competent set of eyes can significantly enhance the quality of the document.

How it is Embedded in the Workflow

After receiving a task, as a technical writer, you:

• Arrange a meeting with a subject-matter expert, a.k.a. the SME, to elicit necessary information for the future document.
• Prepare for the interview: you need to be ready to ask questions and introduce topics to discuss. It is essential to check the requirements for the document with the customer beforehand. A silly yet accurate example: you might think that the document should contain information on how to grow carrots, and the customer wanted information on how to cook them. Right understanding of the task — a necessary start for a good document.
• After meeting the SME, prepare the first draft of the document and send it back to the SME for checking the correctness of the facts.
• Once all the comments from the SME are taken into account, send the document to your team for a cross review, and this is where the magic truly happens.

Now, the sequence SME -> team is slightly controversial because some prefer to send the document draft to the team first, and then to the SME. We have decided that it would unnecessarily increase the workload. After the team’s review, the SME might add crucial and vast in volume comments to be addressed. This means that you would have to send the updated version for a team review again. It might look like an entirely different article. Extra work — do we need it? No, we don’t.

Benefits

Even if your teammates have the same grading, everyone has their own forté. So, each reviewer will be checking the document from a different angle, which will greatly improve the quality of the document. For example, structuring skills, creating simple explanations for complex concepts, knowing all the technical tricks of the corporate wiki system, a keen eye for stylistic inconsistencies — a good technical writer should have it all, but one skill or another always stands out.

Scaling

If you have a small team, making cross review a mandatory task for every teammate is worth it. But in the case of a medium-sized team, making everyone a reviewer is an overkill. The job of a manager is to understand the strong suits of each employee and assign tasks accordingly. For example, reviewing a company-wide policy is different from reviewing a guide for a developer: the former praises formalization and attention to the details, the latter — getting to the point without any ado. Choosing the right person for the job will ensure a great result.

And if your team is extensive in size — well, I am sure you already have a dedicated employee for reviewing documents.

Ground Rules

We have reached the most interesting part — the basics of each review.

• Style guide. You should have one. The more tailored the guide is to your specific field, the more effective it becomes. While using established style guides like the Google one can be helpful, customizing one to the specifics of the product, featuring fewer but more precise rules and examples, is often the optimal approach. The style guide is needed when a technical writer is not sure about a certain rule, or there are different interpretations of its usage, and you need to have a common source to resolve such conundrums. The pinnacle of your style guide success is when not only technical writers start using it while creating documents, but other teams take note of it.
• Right to disagree. You do not have to agree with every comment you receive in your document. If you see that your version is better — defend it but provide a solid proof. After all, we have the same goal — to make the document better, so constructive arguments are not your enemy.
• Upper hand. If a certain discussion turns into an unnecessarily long one, it is important to have a person in the team who will take the responsibility and choose the most suitable option. Most likely, it will be the team leader, but if you have employees of various grades, you can delegate the Upper hand role to the senior technical writer.
• Respect. This rule applies to life in general, but especially in cross reviews — always express your opinions firmly but tactfully. If you disagree with something, support your viewpoint with strong, well-reasoned arguments.
• Not basing opinions on taste. A simple rule — if you can’t provide any argument why something should be changed, you have no ground to stand on. Everyone has their own taste, but while doing a review, think first about the purpose of the document, the audience, used techniques, and only after that (if you really want to) — your personal taste.
• Minding the time. The high quality of the review should always prevail, nonetheless, always consider the proportion of time and effort. Too brief, and the review may lack depth; too lengthy, and it can become overly exhaustive. Here the “good enough” principle might come in handy.

Food for Thought

As a starting point, you can introduce this practice for a certain type of document, not all of them. For example, for documents that are needed in a meticulous form, like policies. Or for documents which have the lowest reading rate and/or are difficult to read and need significant revision.

And by-the-by, this practice can create a healthy atmosphere of professional community among your teammates, as it encourages you to learn more about technical writing, and to bring the A-game to the table while reviewing and writing documents.