17 bad tips for those who check documentation and technical texts

Do you write documentation, articles or other texts? Then, for sure, you have inspectors. I am sure that you love your inspectors dearly and reverently. You'll most likely be looking forward to them sending you their edits and comments. You reverently study and re-read the nuggets of wisdom that the examiners have graciously shared with you. You write down the best comments in a special notebook or even print them out and hang them on the wall… By the way, seriously, I sometimes do this. Let’s say I haven’t gotten around to printing out quotes yet, but I already have a special “notebook”. More precisely, a text file.

Often I myself have to act as a “stern reviewer” and proofread the documentation and texts that technical writers write. At the same time, I see and analyze the comments that other reviewers left on these texts. I started collecting the most enchanting comments. I do this in order to have a counter-example before my eyes – how in no case should you write comments on other people’s texts.

My bad advice is a kind of quintessence of these entries – carefully selected, systematized and distilled advice for inspectors. A practical guide to driving your technical writers and writers crazy.

Disclaimer. Any similarities between fragments of this text and actual comments in your documentation are completely coincidental. No reviewers were harmed during the writing of this text.

1. Write comments as emotionally and vaguely as possible: “Yes really?!“, “Wow!“, “Tin” This will enliven the communication process.

2. In general comments, be sure to write: “The entire document needs to be rewritten! Even if you only corrected a couple of minor errors in your comments to the text of several hundred pages. This will keep the writer on his toes.

3. Instead of explaining how to fix a bug, ask the technical writer a question: “Is this how it works?“

4. Better yet, write a comment consisting of one question mark. Or just write: “This is wrong” It will be interesting for the writer to guess how everything really works.

5. If you are not a professional editor or proofreader, then try to correct the style of the text as often as possible. Give the writer tips on how to write better sentences.

6. Write comments like “This is a must check” The writer likes to have fun testing the system.

7. After the writer has finally tested the system and made sure that everything was specified correctly, write that you wrote this comment “For myself“

8. Send comments half an hour before the document is due to be shipped to the customer. It will be useful for a writer to practice the important skill of stress tolerance.

9. Never take responsibility for the correctness of the information provided. In each comment, use the words: “Seems“, “Maybe“, “like” The document is written by the writer, and he will answer.

10. Never inform the writer about important changes in the logic of the system made during development. A technical writer must independently sift through hundreds of submissions and find those that are relevant to the topic of the document. If you don’t find it, it’s your own fault. Tell him about this when checking the document: “This is no longer the case!“

11. It’s even better not to apply at all. It's up to the technical writer to figure out that the button now works differently. Intuition is his professional quality. In general, it is better to record less information about the operation of the system in writing. Writing is the job of the writer.

12. Insist that the writer use slang terms in the text: “That's what everyone says, it will be clearer to the customer“

13. The more people check the document, the better. The writer will be interested in solving the logical problem of combining corrections that are opposite to each other.

14. Do not make comments directly into the document being checked. It is better to send each comment to the text as a separate message in the messenger. If you find an error, immediately send it to the writer. It will be interesting for him to take a break from another document he is currently working on.

15. Insert a comment often: “This needs to be rewritten!” The writer is a professional in his field. It will be obvious to him what exactly the reviewer did not like in the selected fragment of text.

16. Never check a document completely. When you re-proofread, find errors in parts that have already been checked. The more iterations of verification, the more interesting and intricate it becomes.

17. After several iterations of corrections of the same place in the text, return to the original version. Write that “It got so much better“