Amey-Thakur Comments and annotations
A comment points at content, and the content moves. Nearly all the difficulty is in the anchor: keeping a note attached to the right place after the text around it has been rewritten, or admitting honestly when it can no longer be placed.
Method
- Anchor to stable identifiers, not offsets. Character positions break on the first edit above them; anchors tied to content identifiers or ranges survive far longer (see collaborative-editing-models).
- Define orphan behaviour explicitly. When anchored content is deleted, the comment must become visibly orphaned rather than vanishing, because it may be the more important record.
- Keep threads shallow. One level of replies covers nearly every real discussion and stays readable; deep nesting does not.
- Make resolution meaningful and reversible. Resolved comments hide by default and remain retrievable, since resolution is often premature.
- Notify precisely. Mentions notify the person mentioned, thread participants get replies, and everyone else gets nothing, or comment notifications become noise people disable (see notification-fatigue).
- Show comments in context, not only in a list. The location is half the meaning, and a sidebar list divorced from position is much harder to act on.
- Include enough context in the record. Quoting the anchored text at comment time means the thread still makes sense after the content changes (see version-history-ux).
Boundaries
- Comments are discussion, not change tracking; suggesting edits is a different feature with different semantics.
- Comment content is user data with its own retention and export obligations (see right-to-erasure).
- Anchoring in rich structures such as tables and images is substantially harder than in flowing text.