--- title: Comments and Mentions slug: comments-and-mentions kind: pattern summary: A discussion attached to the record it is about, where naming someone notifies them — so context and conversation stay in the same place. problem: >- The decision about a record was made in a chat thread or an email that nobody can find six months later. The record shows the outcome and none of the reasoning, so the next person re-litigates it or repeats the mistake. family: [coordinate] data_shape: [record] principles: [minimize-distance, orientation] interaction: [editing, feedback] density: medium complexity: medium status: stable visibility: public use_when: - Decisions about a record need discussion, and the reasoning matters later. - More than one person touches the record. - The conversation currently happens in chat or email and gets lost. avoid_when: - One person works alone. A notes field is simpler and enough. - The discussion is really about the process, not this record — that belongs somewhere shared. - The record is high-volume and low-stakes; a comment box on every row is noise nobody reads. alternatives: - slug: activity-timeline when: You need the record of what changed, not a discussion about it. - slug: assign-owner when: The real need is to make someone responsible, not to talk about it. ask_leo: | Add comments to this record. - Put the comment thread on the record itself, below the detail, so the context is on screen while people write. - Typing @ offers people to mention, and mentioning someone notifies them with a link straight to this comment. That is the entire coordination mechanism — without it, comments are a diary nobody reads. - Show who wrote each comment and when, and keep them in chronological order. - Allow editing your own comment for a short window, and mark it as edited. Never allow silent editing, and never allow editing someone else's. - Deleting a comment leaves a visible tombstone that says a comment was removed and by whom. A thread that can be silently rewritten cannot be relied on in a dispute. - Interleave comments with the record's activity events in one chronological thread if you have both, so cause and discussion sit together. - Let people who are not mentioned follow the record, and always notify the owner. - Never notify someone for their own action. related: - title: Activity Timeline url: /patterns/activity-timeline summary: The system half of the same thread — what changed, alongside what was said. - title: Assign an Owner url: /patterns/assign-owner summary: Who gets notified by default, and who is accountable for acting on a comment. --- ## Anatomy ``` ┌─ Comments ────────────────────────────────────────────┐ │ Dana · 3 days ago │ │ @priya the labour hours on level 3 look high — can │ │ you check against the timesheets before we send? │ │ ↑ notifies Priya │ Priya · 2 days ago (edited)│ │ Checked. 48 hours is right, two crews for three days. │ │ │ │ ⌁ Dana changed the amount from $8,400 to $8,900 │ ← activity, │ 2 hours ago │ interleaved └───────────────────────────────────────────────────────┘ ``` - **On the record**, so the thing being discussed is visible while discussing it. - **Mention notifies.** This is the whole pattern. Comments without mentions are a diary. - **Edits are marked, deletions leave a tombstone.** A thread that can be silently rewritten is worthless in exactly the situation you kept it for. - **Interleaved with activity**, so "why did the amount change" and "the amount changed" are adjacent. ## Why it works It puts the reasoning next to the record. The alternative is not "no discussion" — the discussion always happens. The alternative is that it happens in a channel with no connection to the record, and is therefore unfindable at exactly the moment someone needs it. Mentions are what make it a coordination tool rather than an archive. A comment that nobody is told about is a message in a bottle; @-naming someone turns the record into the place work gets asked for, which is what pulls conversation out of chat. ## The retention argument Comments accumulate the *why* behind decisions, and that turns out to be the most valuable and least reproducible content in an internal system. Anyone can reconstruct what a record says; almost nobody can reconstruct why it says that. This is also why the integrity rules matter more than they seem. Silent editing and silent deletion are cheap to allow and quietly destroy the one property that makes the thread worth keeping. ## Getting it wrong - **Comments with no mentions**, so nothing is ever seen in time. - **Silent edit or delete**, which makes the thread untrustworthy. - **Notifying people about their own actions**, which trains everyone to ignore notifications. - **A separate "internal notes" and "comments" split with no clear rule**, so people put things in the wrong one and something private reaches a customer. - **Comments on high-volume records nobody reads**, which is noise disguised as collaboration. - **No link back from the notification**, so being mentioned means going to find the record yourself. ## Exemplars **GitHub issues** are the reference: the discussion, the activity and the record are one thread, and years later the reasoning is still attached to the code it produced. **Linear** interleaves comments and property changes in one timeline, which is the detail that makes "why did this move to blocked" answerable in one glance. **Google Docs comments** show the strongest version of proximity — the comment is anchored to the exact text it is about, which is as close as this pattern can get. The extractable rule: **comments preserve the why, and mentions are what make anyone read them.** Build the mention, or you have built an archive.