Commenting

Added
Purpose
Let people attach remarks to a passage of shared material and settle them.
Operational principle
If a member marks a passage and writes a remark, others see the remark beside the passage and can reply; once the matter is settled, whoever resolves the thread takes it out of view without deleting it.
State
  • author: Comment -> one User
  • about: Comment -> one Item
  • anchor: Comment -> opt Range
  • thread: Comment -> one Thread
  • replyTo: Comment -> opt Comment
  • resolvedBy: Comment -> opt User
Actions
  • addComment A member writes a remark about an item, or about a passage of it, which starts a thread.
  • replyToComment A member adds a remark to a thread in answer to an earlier one.
  • resolveThread A member marks a thread settled; it leaves view, its remarks are kept, and who resolved it is recorded.
Misfits
  • A thread whose passage is deleted keeps its remarks and loses its place.
  • Resolving hides a thread from the people who have not read it yet, and what was settled there is invisible to anyone reading only the material.
  • A passage that starts being referred to, not only discussed, is a weak object; a highlight with a thread has no identity of its own.
  • A remark edited after it has been answered changes what the replies were answering, unless the edit is marked.
  • A remark outlives its author's membership; the thread keeps it and author names someone who has left.
Also called
discussion, annotation, review comment, thread
Appears in
Google Docs, Figma, GitHub pull-request review, Notion

Patterns that act on it