When you are asked to perform a review:
- Show respect to the author. Be polite, clear and to the point. Judge the document and not the person.
- Look at the document from your own role. For example: Is it consistent with your design? Does it describe all situations in a SMART way so you can be confident your test cases will cover all risks? Are you confident the use cases cover all business needs?
- Don’t look for defects that others will find from their role (but note them down anyway when you run into them)
- Write down your comments in such a way you are helping the author to improve his document. Don’t just say ‘You did it wrong’.
- Since you probably have to read the document anyway, try to combine your review with other activities like high level designs/test cases/modeling etc.
- Unsure about your comment? Note it down, the worst that can happen is that your comment gets rejected.
When writing your comment, make sure to be complete and detailed enough so the author understands your comment ánd is helped in reworking the document. Let’s take a look at the following examples:
“This text is unclear to me.” – What is unclear? Why is it unclear? What amount of detail do you want? Better would be “Please clarify this text by exactly describing the context in which the situation can occur.”
“You probably don’t know what you’re saying here.” – Respectless judging the author instead of respectfully judging the product. Not helpful to get it fixed. Better would be “This description is incorrect. Please refer to the glossary for a correct description.”
“Why is this action needed here? ” – 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. Better would be “Following the standards as described in the design guidelines, this action must be prevented here. See the design of X for an example of an alternative way to handle this situation.”
The role of the reviewer
Naturally, the reviewer is playing an important part in a review process. Actually, there are multiple roles a reviewer fulfills. The reviewer should be aware of these roles as it impacts the review, the communication about comments and the expectations of the results of a review.
The reviewer as a stakeholder
No matter which stakes a reviewer has: the document serves a purpose. Be it informative, a more detailed product of the reviewer’s product, input to the reviewer’s activities or having impact sideways somehow; the reviewer wants the document to be clear, correct and complete. When reviewing a document, the reviewer, from his own (project) role, needs to check if the document complies to their own definition of clear, correct and complete.
From this role, the reviewer must expect the comments to be taken seriously because (especially the Majors) will impact the reviewer’s stakes if not fixed.
The reviewer as a colleague
Most of the time the document a reviewer looks at is created by a colleague. Helping out your colleague to improve his documents is like doing them a favor. Help your colleagues like you would help your friends or family when they ask you to help.
From this role the reviewer delivers comments with less expectations on the rework; it’s up to the author to approve or reject the comments.
The reviewer as an assistant
Sometimes the reviewer is no stakeholder and not a direct colleague, but for example is a subject matter expert. These reviews most of the time are not the first moments of contact between author and reviewer. Most of the time the subject matter expert was involved in the creation of the document. The review is meant to check if previously discussed facts are trusted to the paper correctly.
Reviewing as a subject matter expert you do not always have stakes involved, you are not always reviewing to help the author, but you are in a sense checking that your previous investment lead to correct output.
The reviewer as a human
Unless the review is somehow done in an automated way, the reviewer is a human as well. That means that emotions, history, technical and textual capabilities, availability and relationships play a role. One cannot expect a reviewer to be a constant factor in these fields. One important property is that most humans like some kind of positive feedback. That means that the human in the reviewer expects a serious response on each comment. Reviewing and commenting took time, was done seriously so expectations are equal: time must be taken to seriously consider all comments. No matter the importance. Without this serious feedback loop, the reviewer will most likely put less effort in a next review.