Technical Reviews

A Quick reference guideline for the reviewers

When you pick up tech artifacts for review, often, you may be in the middle of solving another problem completely unrelated to the article. As you know the subject, and you love technicalities, the tech article reviews often seem simpler.

On a good day, you usually catch all the errors with plain eyes. Sometimes, even on a good day, your mind may run parallel threads. Chances are, flaws may slip as easily as water through fingers in your open palm. That’s why it helps to have a quick reference for tech reviewers.

This article is an attempt to list all the possible general checks that a tech reviewer may have to think about. It is an off-shoot of working with technical documentation over time. This reference does not have review pointers specific to the technology, as you are the best person to review the artifact in the technical angle. Keep adding pointers to your Notes, to ensure continued improvements in all your tech review rounds.

Are you ready to review the work?

If you find yourself saying “Yes” to these questions now, you are ready to do a technical review:

1. You can devote fifteen minutes of undivided attention to the document in front of you.
2. You like technical or techno-functional documents.
3. Your last half-hour had no points that are emotionally, physically, or mentally affecting you now.
4. You have no common cold or fever.
5. You have no personal differences with the author or stakeholders specific to the document.
6. The feel-good is nice inside and outside of you.

While it is always not possible to put up a brave, kind, optimistic, smiling, and great face, it is important to know that as a reviewer, your mind and mood can define the quality of your review, unless your job is to review documents and you know how to be a cleaned slate before every review.

[Constant practice often excels even talents!]

Check your balanced mind before you start a documentation review.

Are you ready?

Take a pleasant break of five to ten minutes at the least before you do a tech review.

Why? It helps to leave behind your racing thoughts about a previous meeting, a work or personal issue.

Keep a clear head.

How? Take a few deep breaths to get to the NOW.

Why? It is also another’s work product. Mindfulness is essential for a fair review.

Get Deepa Sriram’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Here are the plus points you should look for:

1. Cohesive thought flow.
2. Context and Background.
3. Relevant simple diagrammatic representation.
4. Simple descriptions of complex looking technical drawings.
5. Mention of percentages as data points instead of actual numbers.
6. Relevant links that are limited to official references on the subject or an approved and relevant organisational web link.
7. Simple language without colloquialism and jargons.
8. Source credits.
9. Technical correctness, completeness, and adequacy.
10. Integrity.

Appreciate the plus points, so the author can keep it up further.

Common mistakes

1. Ambiguity in sentences.
2. Redundant pointers across paragraphs or sections.
3. Unnecessary tangents luring the reader away from the core message thread.
4. Extra information that may lead to more questions, often unrelated to the topic of discussion, but running the danger of potentially unintended consequences on the organisation — reputation, profit, business, policies, or values.
5. Missing statements about technical assumptions.
6. Missing statements about standard well-known technicalities that can leave newbie readers in the dark.
7. Patentable idea written as a part or whole in the article.
8. Information or data point that may be construed as an input, an idea, or a hint to the competition to understand pointers that may adversely affect business.
9. Direct copy-paste of content from the internet, unless it is a quote with due credits.
10. Code segments with real filenames and data points that give away more than they should, to an intelligent competitor.

Know that these happen to the best of us, many times.

Understand the mistakes

Most mistakes in writing are because of one or more of the following reasons:

1. We repeat and reword the subject in our mind in a way that makes sense for our understanding when we write.
2. We like to recall sometimes.
3. The fastest traveler is the mind. Our thoughts gallop faster than the speed of light.
4. We love to explain as we believe in teaching others just the way we like to be taught.
5. We are so sure sometimes that we involuntarily assume things.
6. We are so thorough that we don’t realise it may be new to the readers.
7. We don’t realise that we have a unique idea.
8. We mean to be resourceful and data-centric.
9. We focus on our topic and use common explanations from the internet without realising that they are also copied text and not definitions.
10. Inadvertent copy-paste errors are common when you work on code explanations.

When you understand, you can be kind!

Inform your writers

You can choose to share the following pointers with your writer:

1. Say it once and say it right.
2. Say what’s necessary.
3. Cut the extra words and sentences wherever possible.
4. If it’s an assumption, mention why.
5. Explain terminologies and jargons or provide suitable reference.
6. Remove IP or potential IP content.
7. Check data twice to begin with and repeat as required.
8. Run a plagiarism check on any reference you want to use. Reword if you find it is already a plagiarised information.
9. Scan thoroughly for your organization-specific filenames, functions, and meaningful variables in your code examples. Edit them all.

A Review is a two-way learning journey!

What if you are not ready to do a technical review?

Your options are:

1. Pass it on to another reviewer.
2. Buy more time for review and do it when it feels right.
3. Ask for a co-reviewer to collaborate with you on the review.
4. Say “No” to the review.

It’s okay. Sometimes, we all need a little more time!

Conclusion

This reference stems from an experience spanning two decades of technical writing and seven years of manning a technical blog in the capacity of a technical writer, third-eye reviewer, and editor of a technical publication on medium. I hope you find these useful.