DEV Community

juan pablo abadia medina
juan pablo abadia medina

Posted on

A documentation exercise for an ambiguous review request

Take this fictional review request:

Categories are ready. Please review.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. Which artifact and version am I reviewing?
  2. What action should I perform?
  3. 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)