Did you read I am a reviewer?
Comments belong in a review form, questions do not.
Comments will lead to rework of the document, improving the quality of the document. A comment is about fixing defects, preventing defects (for instance by asking for clarification) and making the document fit for purpose. If a comment gets rejected, the author can provide a valid reason for that.
A comment is a statement with a few purposes. A comment
- is clear about what the reviewer wants;
- helps, or directs, the author in reworking the document based on the comment;
- is complete in terms of what is found, what is expected and what is wrong/unclear;
- is (also) complete in terms of spelling, grammar and interpunction;
- is written as a statement and is prioritized;
- shows respect to the author, is aimed at the document and is objective and factual.
Questions tend to be answered in the review form, causing the knowledge to fade since a review form is not part of the project’s documentation.
A question is something a reviewer might have when performing a review. A question can arise because of
- missing information;
- a gap in the reviewers’ knowledge.
In the first case: note down a comment in the form of a statement that more information is required. In the second case: ask a colleague to clarify or ask yourself if you are correctly selected as a reviewer for this (part of the) document.
First, read Find your Majors.
Second, ask your more experienced colleagues about their strategy, way of working, checks and methods.
Third, browse the internet and read some books:
– How to write a peer review
– Perspective based reading
– A Structured Approach for Reviewing Architecture Documentation
– Object-Oriented Reading Techniques for inspection of UML Models
Reviewing without a specific goal can be OK, but it can also lead to unnecessary long reviews, less important comments or missing issues. To get focus, contact your moderator to get things to explicitly look for. Maybe your moderator already provided you some suggestions.