A tagging system for documentation review comments

Summary

Every comment in the review looks equally urgent.Formatting notes sit beside broken code examples.The team spends 30 minutes debating comma placement while critical bugs slip through.To fix this, I introduced a tagging system for review comments.I see this pattern in docs reviews: reviewers leave comments without indicating priority. Contributors treat every comment as blocking. The breakdown happens in three ways:Contributors waste time on non-issues: Someone suggests “maybe use a bullet list here instead of numbered?” The contributor spends an hour reformatting. Turns out it was just a passing thought.Critical issues get missed: Seventeen comments deep, one mentions the API endpoint is wrong. The PR merges. Users hit a broken example. Support tickets pile up.Review cycles multiply: Contributor fixes what they think matters. Reviewer expected different fixes. Another round. The two-day PR becomes a two-week ordeal.The root cause: no shared language for priority.The fix: a two-part tag for every review comment: severity + category.SeveritySeverity tells contributors the importance of the fix.blocker: Must fix before merge. Breaks functionality or blocks critical understanding.improvement: Should fix before publication. Improves clarity, structure, or usability.optional: Personal preferences, stylistic suggestions, future ideas.CategoryCategories tell contributors more context about what kind of fix to make at first glance.clarity: Confusing or incomplete explanations.bug Incorrect code, wrong output, factual errors.organization: Issues with flow, structure, content order.style: Wording, formatting, tone.consistency: Conflicts with other sections, terminology, or examples.Add others if your team needs them. Keep the list short.(improvement, clarity): Step 3 assumes readers know what environment variables are. Add a one-line explanation or link to prerequisites.(blocker, bug): This code example throws an error. Missing import statement at the top.(improvement, organiz...