{"slug":"activity-timeline","meta":{"title":"Activity Timeline","slug":"activity-timeline","kind":"pattern","summary":"A record's history as an ordered list of events — who did what, when — so \"how did this get like this\" is answerable without asking anyone.","problem":"A record shows its current state and nothing about how it got there. When something is wrong, the only way to reconstruct the history is to ask colleagues what they remember, and the answer arrives hours later and partly wrong.","family":["scan","inspect","coordinate"],"data_shape":["record","collection"],"principles":["orientation","progressive-disclosure"],"interaction":["scanning","disclosure"],"density":"medium","complexity":"medium","status":"stable","visibility":"public","use_when":["Several people touch the same record over time.","Disputes, audits or support questions turn on what happened and when.","The record has a lifecycle, so transitions are meaningful events."],"avoid_when":["The record is written once and never changes.","Nobody would ever ask how it got to its current state.","The events would be almost entirely machine noise, drowning the human ones."],"alternatives":[{"slug":"version-history","when":"People need to see and restore previous CONTENT, not a log of actions."},{"slug":"lifecycle-status","when":"Only the current state matters, and the path to it does not."}],"ask_leo":"Add an activity timeline to this record.\n\n- Record an event for every meaningful change: state transitions, field edits\n  that matter, comments, assignments, and anything sent to a customer.\n- Each event shows who, what and when, in that order of prominence. Use a\n  relative time with the exact timestamp available on hover or alongside.\n- Order newest first if people mostly check \"what just happened\", oldest first\n  if they mostly reconstruct a story. Pick one and keep it consistent.\n- Write events as plain sentences in the past tense, naming the actual change:\n  \"Dana changed the amount from $8,400 to $8,900\", not \"Record updated\".\n- Distinguish human actions from automated ones visually, and let the\n  automated ones be filtered out. System noise is what kills timelines.\n- Group runs of similar events by the same person within a few minutes into\n  one collapsible entry, so a bulk edit is one line rather than forty.\n- Never delete or rewrite an event. A timeline that can be edited is not a\n  record of anything.\n","related":[{"title":"Lifecycle Status","url":"/patterns/lifecycle-status","summary":"The state transitions that produce the most useful timeline events."}]},"body":"## Anatomy\n\n```\n  ● Dana Whitfield · 2 hours ago\n    Changed amount from $8,400 to $8,900\n    \"Client added the second riser.\" \n\n  ○ System · 2 hours ago\n    Recalculated tax                        ← automated, quieter, filterable\n\n  ● Priya Nandi · yesterday\n    Moved from In review to Approved\n\n  ⌄ Dana Whitfield · 3 days ago\n    Edited 12 line items                    ← 12 events collapsed into one\n```\n\n- **Who, what, when** — in that order, because \"who\" is the question people ask\n  first when something is wrong.\n- **Human events louder than machine events**, and machine events filterable.\n- **Runs collapsed.** A bulk edit is one line with a count, not forty lines that\n  bury everything else.\n- **Append-only.** An editable history is not a history.\n\n## Why it works\n\nIt answers the question that current state cannot: **how did this get like\nthis**. That question drives a surprising share of internal support work, and\nwithout a timeline the answer lives in people's memories, which are slow to\nquery and unreliable.\n\nIt also changes behaviour. When actions are attributed and visible, people are\nmore careful and more willing to fix things, because the fix is attributable too.\nThat is worth more than the audit trail itself in most teams.\n\n## The signal-to-noise problem\n\nTimelines fail almost entirely one way: **automated events drown human ones.**\nA system that logs every recalculation, every webhook, every cache refresh\nproduces a timeline where the one line that matters — a person changed a price —\nis on page four.\n\nTwo mechanisms fix it, and you need both:\n\n1. **A visual distinction** so the eye skips machine events without reading.\n2. **A filter** that removes them entirely, remembered per user.\n\nIf the noise is bad enough that the default view is useless, the honest fix is to\nstop recording events that no human will ever want, rather than to filter harder.\n\n## Getting it wrong\n\n- **\"Record updated.\"** An event with no content. If you cannot say what\n  changed, the event is not worth storing.\n- **No attribution**, so the timeline answers when but not who — usually half\n  the question.\n- **Absolute timestamps only.** \"2026-08-14 09:12:44\" is precise and requires\n  arithmetic; \"3 weeks ago\" is what people actually think in. Show both.\n- **Uncollapsed bulk runs**, which push everything meaningful off the screen.\n- **Editable or deletable events**, which makes the whole thing untrustworthy —\n  and it only takes one person knowing it is editable.\n\n## Exemplars\n\n**Stripe's payment timeline** leads its detail view with the sequence of events,\nbecause for a payment the history *is* the record. It also shows the value of\nnaming events precisely: \"Payment failed — insufficient funds\" answers the\nsupport question on its own.\n\n**GitHub's issue timeline** interleaves human comments with state changes and\nreferences, and gets the collapsing right — long runs of automated activity fold\naway without disappearing.\n\n**Intercom's conversation view** demonstrates the human-versus-machine\ndistinction handled visually, so a person scanning for what a colleague said is\nnever reading bot events.\n\nThe extractable rule: **a timeline is only as useful as its worst event\ndescription.** One \"Record updated\" teaches people the log is not worth reading,\nand they stop.\n"}