Comments in Technical Documentation: Dos & Don’ts

Purpose and Function of Comments in Technical Documentation

In technical documentation, comments serve as a valuable communication tool between authors and reviewers. With well-placed comments, you can provide feedback, note unclear points, or make improvement suggestions, without changing the published text itself.

Especially in collaborative writing processes, comments help identify and resolve problems or inconsistencies early on. Similar to how code reviews in software development help find errors and ensure code quality. Beyond error detection, reviews also support knowledge sharing within the team:

• New members receive feedback on conventions and best practices,

• Knowledge is shared,

• a culture of quality emerges

Similarly, comments in documents foster such a quality culture. They make it easier to:

• ensure consistent writing style,

• clarify open questions,

• and create shared understanding about the content.

Another purpose of comments is to record to-dos or open points directly in the text. Instead of relying on your memory or keeping separate notes, you simply write in the draft:

//  TODO: Update diagram once new data is available

Such internal notes don't go into the published documentation, but remind everyone involved which sections still need to be worked on.

Overall, thoughtfully used comments make the documentation process more efficient: They communicate directly in the text what should be improved or checked, and ensure that nothing is overlooked during review. Through clearly visible hints, reviewers can precisely understand what thoughts the author had at specific points, or where they need feedback. The result is more precise, consistent technical documents – created in an atmosphere of open communication.

Do's and Don'ts of Helpful Comments

Not every comment is inherently helpful. It depends on how you comment. Therefore, observe some basic rules so that your feedback is constructive and welcome:

Do's – what you should do:

• Comment clearly and concretely: Address specific parts of the document and explain precisely what you notice. For example, instead of "Unclear" better "The installation section is unclear – why do you need to do X first?". The more specific your comment, the easier it is for the author to address it.

• Stay factual and respectful: Phrase things in a polite, professional tone. Criticize the content, not the person. Focus on the documentation itself and not its author. Through factual, respectful comments, you signal that it's about improving the document, not personal criticism.

• Make constructive suggestions: When you point out a problem, offer an improvement suggestion whenever possible. A helpful comment could be, for example: "// Suggestion: Perhaps a code example would be useful here to clarify the step." This gives the author direction instead of just pointing out deficiencies.

• Give praise where it's deserved: Don't hesitate to highlight positive aspects. Sincere recognition motivates and shows the author what works well. A brief "// Praise: The introduction explains the problem very clearly. Well done!" can help ensure your counterpart remains open to critical feedback.

• Ask questions to improve understanding: When something is unclear, formulate a question instead of a statement. For example: "// Question: Would you perhaps explain in more detail how this module is configured?". Through questions, you encourage an explanation without rushing to judgment. This personal approach seems less confrontational and opens up a conversation.

Don'ts – what you should avoid:

• Absolute claims and commanding tone: Avoid formulations like "This must be changed" or "You should …​". Such expressions quickly sound patronizing or aggressive. It's better to emphasize your own perspective ("From my point of view, one could…") and leave room for discussion.

• Personal attacks or blame assignment: Comments must never be directed against the person themselves, but always refer to the document. Avoid sarcastic or derogatory remarks ("Wrong again…"). Such comments have no place in a productive, collaborative review. Always stick to the subject matter: "This formulation is ambiguous" instead of "You wrote this ambiguously".

• Vague criticism without context: Statements like "This is bad" help no one. If you dislike something, explain why and, if possible, how it can be improved. Unjustified criticism only frustrates, while reasoned feedback initiates a learning and improvement process.

• Formulating "Why?" as an accusation: Direct "Why did you…?" can seem defensive, as it's often understood not as a genuine question, but as hidden criticism. Instead, ask openly about background: "What was the thought behind this structure?" – this shows genuine interest without implying something is wrong.

• Too many comments at once: Don't overload a text with a flood of remarks about every little thing. Prioritize the important points. An endless list of comments – especially about minor issues – can overwhelm and demotivate the author. Set priorities so the feedback remains digestible.

By following these do's and don'ts, you ensure an appreciative feedback culture. The goal is for comments to lead to improvements and not to frustration.

Conventional Comments and Other Approaches for Comments

To systematically make comments more helpful, certain conventions have been established in the tech industry. One of the best-known movements is Conventional Comments. This format standardizes how feedback is formulated: Each comment is introduced with a short label that immediately clarifies the tone and purpose.

Such labels - like praise, nitpick, suggestion, issue or question - categorize the comment type and make it more quickly understandable for everyone involved. Interestingly, Conventional Comments is not only intended for code reviews, but generally for any kind of review process, from document reviews to RFC discussions.

Imagine a colleague leaves this comment in the document:

"issue: The description of this feature is unclear."

Just through the prefixed issue, you immediately recognize: Here a problem is being pointed out that should be fixed, rather than a mere suggestion or question. This small addition prevents misunderstandings and ensures more efficient discussions.

Conventional Comments pursues a similar goal as the well-known Conventional Commits for Git commit messages, just for review comments.

Types of Comments in Conventional Comments (with Examples):

These labels are the core categories of Conventional Comments. Some teams expand or vary the list further, e.g., with typo for typos or polish for small quality improvements without acute problems.

What's important is not that every comment is necessarily perfectly categorized, but that everyone involved has a common understanding of these categories. This way, both reviewers and authors immediately know what it's about: A praise requires no action except being pleased, an issue however does. Moreover, the tone is set by the label. nitpick signals "just a small hint," which prevents misunderstandings.

Besides Conventional Comments, there are also other approaches that aim for similar goals. Some teams use, for example, simple prefixes like "Question:" or "Suggestion:" or mark urgency through additions like "(optional)" or "(must)". The concept blocking/non-blocking is also widespread – i.e., making it clear whether a comment represents a mandatory need for change or just an optional improvement.

Conventional Comments explicitly supports this through decorations like (non-blocking) or (blocking), which can be attached to a label. An example would be: "issue (non-blocking): …​" for a hint that describes a problem, but whose resolution is not a prerequisite for publication.

Another important trend is the emphasis on empathy and clarity in comments (keyword Non-violent Code Review). Regardless of the label system used, comments should always be friendly and constructive in content. Movements like Non-violent Communication applied to code and document reviews recommend, for example, using I-messages and avoiding judgments. This means, instead of "This is written incorrectly" better "I found it difficult to understand this sentence". Such approaches can be excellently combined with Conventional Comments: The label provides the framework (e.g., suggestion), and the actual message remains respectful and solution-oriented.

Excursus: Constructive Criticism – How to Criticize Correctly?

Even with the best comment conventions, everything depends on the way criticism is presented. In this excursus, we address how to formulate critical remarks so that they are understood by the counterpart not as an attack, but as help for improvement.

• Talk about the text, not about the author: Keep comments objective. For example, formulate "The description of the process is unclear at this point." instead of "You described this unclearly.". By avoiding personal pronouns like "you," no one feels personally attacked. Stick to the content – the problem lies in the text, not with the person behind it.

• Choose the right tone: The written channel always carries the risk of misunderstandings, as facial expressions and tone of voice are missing. Therefore, consciously pay attention to a friendly, constructive tone. A brief thank you or positively formulated feedback beforehand can work wonders ("Thanks for the detailed description of the architecture. I have a small suggestion…"). Absolutely avoid sarcastic or mocking remarks. These have no place in productive reviews.

• Criticize, but with solution or learning opportunity: Criticism is most effective when you link it with a path to improvement. Explain not only what's wrong, but why it's problematic and how it could be done better. Example: "A definition of the technical term is missing here. This could confuse readers without background knowledge. Perhaps we can add a brief explanatory sentence?" – This way the author recognizes the problem and has a direct approach to the solution.

• "I have…" instead of "One should…": Share your perspective without making it absolute. Statements like "One doesn't understand it this way." sound generalized. Better: "I didn't immediately understand at this point how X works." This shows it's your impression and invites clarification, instead of generally judging about "right" or "wrong". This personal approach seems less confrontational and opens up a conversation.

• Ask questions and find solutions together: Constructive criticism also means staying in dialogue. Ask when something seems inconsistent to you ("What do you think about adding a diagram here for clarification?"), instead of demanding changes apodictically. This gives the author the chance to explain their view or work out a solution together with you.

• Consider timing and scope: Think about which criticism points are really relevant. Prioritize essentials (content, comprehensibility, technical correctness) over stylistic details, unless the latter violate fixed guidelines. And: Not everything needs to be commented on in a single review pass. When very many points come up, it's sometimes more sensible to seek a personal conversation or divide the remarks, so the other person isn't "overwhelmed". Practicing constructive criticism requires empathy and practice. Always remember that on the other side a person is reading your words. The goal is to offer support instead of exposure. When criticism comes in the right tone and context, it's much more readily accepted by the counterpart – and that's exactly what we need to continuously improve documentation together.

Comments in AsciiDoc with adoc Studio

Now the practical question arises: How do you concretely implement all these comment techniques in your documentation, especially when you use AsciiDoc as a format? Fortunately, AsciiDoc supports comments directly and enables seamless integration of the above-mentioned conventions.

adoc Studio – a popular editor for AsciiDoc documents – also uses this syntax natively, so you can work comfortably with it while writing and reviewing.

Inline Comments in AsciiDoc:

When you start a line in an AsciiDoc file with //, it is treated completely as a comment. Everything that appears in this line after the two slashes is ignored by the AsciiDoc processor. The text therefore does not appear in the exported document. You can use this to attach short remarks directly to individual lines. By convention, a space is added after // and then the comment is written.

// suggestion: Insert an example sentence here for clarification.

Inline comments are excellent for placing Conventional Comments labels directly in the flowing text. A // issue: …​ at a specific location marks, for example, a problem point exactly where it occurs, without disturbing the reader of the published documentation.

Block Comments in AsciiDoc:

For more detailed remarks across multiple lines or entire sections, AsciiDoc offers block comments. These begin with a line //// and only end when //// appears again. Everything in between, multiple sentences or lists, is completely hidden.

////
issue: The following section is still unclearly formulated.
Please clarify. Perhaps add a diagram?
////

You can use block comments to deposit extensive feedback or discussion points directly in the text, without disturbing the reading flow in the source text through many individual // lines. adoc Studio also recognizes these block comments and usually highlights them in color in the editor, so you can see at a glance which passages are internally commented out. Especially in teams, this native comment function plays to its strengths. Every participant immediately sees all colleagues' remarks in the source code, cleanly separated from the actual content.

adoc Studio for Mac, iPad & iPhone

Create Technical Documentation
with AsciiDoc

Free 14-Day Trial

A practical tip: Also use comments to refer to style guides or decisions. If your team has agreed on a certain writing style, you can insert a block comment in the review process like:

////
nitpick: According to the style guide, we should not use passive forms.
Could you rephrase this sentence actively?
////

It helps to possibly include a link to the style guide in the comment. Such hints anchor quality standards directly in the text and make it easier for the author to understand the reason behind a remark.

Conclusion

Comments are more than just "notes in the margin." When used correctly, they become an integral part of a professional documentation workflow. By following clear conventions like Conventional Comments, heeding do's and don'ts for the tone of your criticism, and exploiting the technical possibilities of AsciiDoc/adoc Studio, you ensure that your feedback is understood and appreciated.

Written by:

Marvin Blome

Content creator and technology enthusiast