Commenting and Annotation System Spec Template

What This Template Is For

Comments and annotations are how async feedback happens in products. Design tools have inline annotations on specific pixels. Document editors have margin comments on highlighted text. Project management tools have threaded discussions on tasks. Each implementation looks different, but the underlying design decisions are the same: where can users place comments, how do threads resolve, what happens when the anchored content changes, and how do users catch up on feedback they missed?

This template covers every decision point for a commenting system: anchoring models, thread lifecycle, resolution workflows, notification design, and permission boundaries. Whether you are building inline annotations for a design tool, margin comments for a document editor, or contextual discussions on data dashboards, this template applies. For the broader collaboration context, see the Real-Time Collaboration Feature Spec Template.

How to Use This Template

1. Start with the Anchoring Model. Where comments attach (object-level, field-level, pixel-level, text-selection) determines the engineering approach and UX pattern.
2. Define the thread lifecycle before notification design. Resolution, reopening, and archival rules dictate what notifications users receive.
3. Walk through the "Content Mutation" section carefully. This is where most commenting systems create bugs: the original content changes but the comment still points to the old context.
4. Use the RICE Calculator to prioritize which surfaces get comments first.
5. Review the filled example, then adapt to your product.

The Template

Anchoring Model

• ☐ Comment attachment level: object (entire document/task), field (specific property), inline (text selection or pixel coordinate)
• ☐ Anchor visualization: sidebar markers, inline highlights, pin icons, or margin indicators
• ☐ Multiple anchoring: can a single comment reference multiple locations?
• ☐ Anchor persistence: what happens when the anchored content is deleted, moved, or edited?
• ☐ Anchor resolution: how does the system map a comment to content that has changed since the comment was created?

Comment Types

• ☐ Text comments: plain text, rich text (markdown/HTML), or both?
• ☐ Attachments: images, files, screenshots, screen recordings
• ☐ Mentions: @user, @team, @all-reviewers
• ☐ Reactions: emoji reactions on individual comments
• ☐ Structured feedback: approve/reject/request-changes actions within comments
• ☐ System comments: automated entries (e.g., "Status changed from Draft to Review")

Thread Lifecycle

• ☐ Reply model: flat replies, nested threads, or single-level threading?
• ☐ Thread states: open, resolved, reopened, archived
• ☐ Who can resolve a thread? (author, any participant, only the original requester)
• ☐ Reopen rules: can resolved threads be reopened? By whom? Time limit?
• ☐ Thread summary: collapsed view showing reply count, last activity, resolution status
• ☐ Bulk actions: resolve all threads, archive old threads

Content Mutation Handling

• ☐ Text-anchored comments: when the highlighted text is edited, does the anchor shift, break, or stick to the nearest match?
• ☐ Pixel-anchored annotations: when the canvas is resized or the element moves, does the pin follow?
• ☐ Deleted content: when anchored content is deleted, mark the comment as "orphaned" and surface it in a separate list
• ☐ Version-linked comments: tie comments to a specific version so historical context is preserved
• ☐ Diff view: in version comparisons, show which comments apply to which version

Permissions

• ☐ Who can comment? (all workspace members, project members, invited reviewers, external guests)
• ☐ Who can view comments? (same as commenter access, or separate "view comments" permission)
• ☐ Private comments: visible only to specific users or roles (e.g., internal team notes on client-facing content)
• ☐ Edit and delete: can users edit their own comments? Time limit? Can admins delete any comment?
• ☐ Guest commenting: do external reviewers need an account, or can they comment via a share link?

Notification Design

• ☐ New comment: who gets notified? (object owner, all watchers, mentioned users)
• ☐ Reply notification: notify all thread participants or only the parent commenter?
• ☐ Resolution notification: notify the comment author when their thread is resolved?
• ☐ Digest options: per-comment real-time, hourly batch, daily summary
• ☐ Unread tracking: per-thread unread state, overall comment badge count
• ☐ Email notifications: include comment text in the email body with a reply-by-email option?

Moderation

• ☐ Report mechanism: flag individual comments for admin review
• ☐ Admin tools: edit, delete, hide, or lock comment threads
• ☐ Content filtering: automated profanity/spam detection
• ☐ Rate limiting: cap comment frequency to prevent flooding
• ☐ Audit log: track all comment actions (create, edit, delete, resolve) with timestamps

Search and Discovery

• ☐ Full-text search across all comments
• ☐ Filter by: author, date range, thread state (open/resolved), object
• ☐ Activity feed: chronological view of all recent comments across the workspace
• ☐ My comments: personal view of all threads the user is participating in
• ☐ Unresolved comments: filtered view showing only open threads

Analytics and Success Metrics

• ☐ Comment volume: comments per object, comments per user per week
• ☐ Thread resolution rate: % of threads resolved within 48 hours
• ☐ Time to first response: how quickly do threads receive their first reply?
• ☐ Comment depth: average replies per thread (signals discussion quality)
• ☐ Adoption: % of objects with at least one comment

Filled Example: Document Margin Comments

Anchoring Model

Comments anchor to text selections within the document body. When a user highlights text and clicks "Comment," a comment thread opens in the right sidebar aligned with the highlighted text. The highlight persists as a yellow background. When the document is edited:

• If the highlighted text is unchanged, the anchor holds.
• If the highlighted text is partially edited, the anchor expands or contracts to match the nearest phrase boundary.
• If the highlighted text is deleted entirely, the comment is marked "orphaned" and moves to an "Unanchored Comments" section at the bottom of the sidebar.

Thread Lifecycle

Permissions

Guest reviewers (via share link) can comment with a display name but cannot resolve threads. Their comments are badged as "Guest."

Notifications

The document owner receives a notification for every new comment. Thread participants are notified of replies. Mentioned users are notified regardless of thread participation. All notifications include the comment text and a deep link to the exact thread position. Unread comments show a badge on the document in the file list.

Success Metrics

Tips for Specifying Commenting Systems

1. Solve the orphan problem before launch. When anchored content is deleted or significantly edited, comments lose their context. Define exactly what happens to orphaned comments. A broken commenting system is worse than no commenting system. See the version history template for how to connect comments to specific versions.

1. Design for the "catch-up" reader. Users who open a document days after a review need to quickly see: how many unresolved threads exist, which ones need their input, and what was already resolved. An unread indicator and a filterable sidebar are essential.

1. Keep resolution simple. Do not over-engineer approval workflows within comments. A single "Resolve" action with optional reopen is sufficient for 90% of use cases. Complex approval chains belong in a dedicated review workflow, not in the commenting thread.

1. Reply-by-email is worth the investment. For async teams, the ability to reply to a comment notification directly from email (without opening the app) significantly increases engagement. It is a moderate engineering effort but a high-impact user experience improvement.

1. Track resolution rate, not just volume. A product with 500 open comments is less healthy than one with 100 comments and a 90% resolution rate. Resolution rate is your signal that commenting is driving decisions, not just generating noise. Use the Product Analytics Handbook for metric framework guidance.

Key Takeaways

• Define your anchoring model first. It determines the engineering approach and drives every UX decision
• Plan for content mutations. What happens to comments when the anchored text or element changes is the hardest problem in commenting systems
• Design for the async "catch-up" reader who needs to quickly triage unresolved threads
• Track thread resolution rate as the primary health metric, not just comment volume
• Keep the resolution model simple. Resolve and Reopen cover 90% of use cases

About This Template

Created by: Tim Adair

Last Updated: 3/5/2026

Version: 1.0.0

License: Free for personal and commercial use