December 20, 2025
Tag or nag?
A tagging system for documentation review comments
Doc wars: Tag your comments to save your sanity… or just add busywork
TLDR: A doc writer suggests tagging review comments by urgency and type to cut merge debates and surface real bugs. The community likes the clarity but worries about “tag fatigue,” pointing to existing conventions and saying daily use is hard—useful idea, tricky adoption.
Docs drama alert: one writer proposes slapping a tag on every review comment—think “urgent,” “nice-to-have,” and “style”—so teams stop fighting over commas while shipping broken examples. The goal is simple: prioritize fixes so merges don’t stall over nitpicks and real bugs don’t get buried. But the community instantly split into camps. Fans say this is the clarity they’ve been begging for (“scan blockers, ship the rest”). Skeptics call it process cosplay, warning the tag pile will become another chore. One commenter pointed to the existing conventionalcomments.org guide and admitted they struggle to use the right tags every day, hinting that good intentions crash into real-life hustle. Cue jokes: someone coined “tag fatigue” and another asked for emoji lanes (🔥 for blocker, ✨ for optional) because if we’re labeling feelings now, might as well go full sticker book. The hottest take? Tagging won’t fix slow reviews or vague feedback—if you write “blocker: vibes,” you’re still blocking nothing. Still, people loved the promise of fewer “should we merge?” debates. The vibe: order vs chaos, with a side of meme energy and a whole lot of “it depends.”
Key Points
- •The article identifies a lack of shared priority language in documentation reviews as a core problem.
- •It proposes a two-part tagging system: severity (blocker, improvement, optional) and category (clarity, bug, organization, style, consistency).
- •Examples show how tags guide fixes, including addressing code errors, clarifying explanations, and reorganizing content.
- •Tagging helps contributors prioritize blockers, reduces overwhelm, and streamlines merge decisions.
- •The system has limits: it cannot fix slow review processes, poor feedback, or replace reviewer judgment.