Take this fictional review request:
Categories are ready. Please review.
What should the recipient do: comment on wording, classify examples or authorize implementation? The request leaves those questions open.
Rewrite the task
For this exercise, assume the author wants feedback on definitions. A more explicit note could read:
Artifact: routing categories, draft 1
Task: classify the fictional examples using the definitions
Feedback: mark ambiguous examples and explain why
Pending: approval for use with real requests
Response location: observations column
The note does not make the categories correct. It describes the action requested from the reviewer.
Try three interpretation questions
Ask a reader to answer using only the note:
- Which artifact and version am I reviewing?
- What action should I perform?
- What remains undecided after I submit feedback?
Compare the answers with the intended task. Record the uncertainty before editing the note.
Add an incomplete-input case
Now remove a definition from one example. Ask where the reviewer should record the missing information rather than inventing a category. If the note has no answer, add a route for questions.
Keep the scope clear
This is a manual documentation exercise with fictional data. It is not an automated test, an approval mechanism or evidence of production performance.
Once the team understands the task, decide how the actual project will store versions, comments and permissions. Those implementation choices need their own design.
What ambiguity would you remove from your next review request?
Juan Pablo Abadía Medina
Top comments (0)