A decision log records what was decided, why, by whom, and under which conditions. Include the alternatives and consequences, then define when the decision should be reviewed. Keep superseded records so a later team can understand why an earlier choice made sense.
Record the choice that someone will question later
A workshop-planning tool lets organizers edit an agenda before participants see it. The team must decide whether every edit should become public immediately or whether organizers should explicitly publish a version. This worked example follows that choice through its first decision and a later revision.
A meeting note might say “Use Save.” That leaves critical questions unanswered: does saving update a private draft or the published agenda, can another organizer see it, and what happens if a save fails? A useful decision record makes the behavior precise enough for a designer, engineer, and future maintainer to interpret consistently.
Michael Nygard’s public architecture-decision-record essay provides a practical precedent: short records retain context, a decision, status, and consequences, and later decisions can supersede earlier ones. The same preservation principle helps product choices, although a product decision log can cover research, scope, and workflow as well as architecture.
Copy this blank decision record
Use one record for one consequential choice. The ID stays stable; the title names the choice rather than the meeting. The context should explain the problem and relevant constraints, not transcribe the discussion.
Link evidence with enough specificity to find it again: a research note, an issue, a prototype version, or an agreed product requirement. If a premise is an assumption, label it as one. A link labeled “research” without a date or finding is hard to use months later.
The person responsible for implementing the change may differ from the person authorized to decide it. Record both when that distinction matters. A review trigger should be observable, such as simultaneous editing becoming a requirement, rather than “review when needed.”
| Field | Copy and fill |
|---|---|
| ID and title | D-[number]: [specific choice] |
| Status and date | [Proposed / accepted / superseded] on [date] |
| Context | [User task, constraint, and decision needed] |
| Evidence and assumptions | [Links and relevant findings] / [unverified premises] |
| Options | [Option A, B, C and their consequences] |
| Decision and reason | [Chosen behavior] because [decisive tradeoff] |
| Decision owner / delivery owner | [Who decides] / [who implements] |
| Acceptance | [Observable checks that express the choice] |
| Review trigger | [New evidence or changed condition] |
| Related records | [Tickets, artifact version, supersedes / superseded by] |
Write the alternatives before the conclusion
For the agenda editor, distinguish draft persistence from publication. “Autosave or Save?” conflates those operations. An organizer may want typing saved automatically while still choosing when attendees see the agenda. Splitting the question produces a more useful set of alternatives.
The table below is the options section of D-001. In this example the team has limited time and has not yet designed conflict handling for simultaneous editors. These are project assumptions, not evidence that autosave is inherently unsafe or more expensive in every application.
The selected option should explain what it gives up. Explicit draft saving requires users to remember an action, so the team must provide unsaved-change feedback. Choosing a familiar button does not remove that obligation.
| Option | Benefit in this project | Cost or unresolved condition |
|---|---|---|
| A. Every edit immediately changes the public agenda | No separate publication step | Unfinished changes become visible; wrong fit for review-before-publish workflow |
| B. Explicit Save draft, then Publish agenda | Clear draft/public boundary with a small first release | User must save; navigation must handle unsaved changes |
| C. Autosaved private draft, then Publish agenda | Draft recovery without automatic public changes | Requires visible save status and a settled multi-editor conflict policy |
A complete filled record: D-001
This example accepts option B for the first release. The important commitment is that participants continue seeing the last published agenda while an organizer edits a draft. The record specifies that boundary instead of merely prescribing a button.
The example evidence pack contains an agreed requirement R-07, “organizers review changes before attendees see them,” and prototype P-03 showing separate draft and public views. The assumption is that one organizer edits an agenda at a time. In your own log, replace these local example references with actual documents or links.
Acceptance checks are deliberately concrete. A successful save changes the persisted draft and its status; a failed save keeps the local edit and offers retry. Publication changes the participant view only after the service confirms success. Those checks let the team review implementation against the decision.
| Field | Worked D-001 record |
|---|---|
| Title / status / date | D-001: Save drafts explicitly before publishing / Accepted / 2026-10-22 |
| Context | An organizer edits a workshop agenda privately before releasing changes to participants |
| Evidence / assumption | Example R-07 and P-03 / one editor at a time is assumed for release 1 |
| Decision | Use Save draft and a separate Publish agenda action |
| Reason | Protect the review-before-publish workflow while keeping release 1 bounded |
| Consequence | Show unsaved, saving, saved, and failed states; warn before leaving with unsaved edits |
| Owners | Maya, product owner, decides; Lee, editor engineer, implements |
| Acceptance | Draft save does not change the public view; publishing updates it after confirmation; save failure preserves edits |
| Review trigger | Simultaneous editing becomes required or observed lost edits make manual saving unsuitable |
| Links | Example requirement R-07, prototype P-03, delivery ticket EDIT-12 |
Supersede the decision when the premise changes
Now suppose a later release requires two organizers to work on the same agenda. The original single-editor assumption no longer holds. That is a reason to reopen D-001, not proof that the earlier team made a careless decision.
D-002 can choose autosaved private drafts while retaining explicit publication. It must address conflict behavior and recovery before implementation. Merely removing the Save button would change the visible interaction without resolving simultaneous updates.
When D-002 is accepted, mark D-001 superseded by D-002 and link back from D-002. Preserve the old options and reason. Do not silently rewrite D-001 to pretend autosave was always the decision: that would erase the explanation for the first implementation.
| D-002 field | Example revision |
|---|---|
| Changed condition | Two organizers must edit the same agenda |
| Decision | Autosave private draft changes; retain explicit Publish agenda |
| Required design work | Define conflict resolution, save status, offline recovery, and which version is published |
| What remains | Participants see a confirmed published version, not each draft keystroke |
| Status | Proposed until conflict and recovery behavior are agreed |
| Relationship | Will supersede D-001 on acceptance; D-001 remains active until then |
Keep the log small and usable
Put a short index beside the records: ID, title, status, decision owner, and last review date. Link the active record from the implementation ticket. The team should be able to discover the current decision without reading every historical meeting.
Create a new record when the choice changes substantially; add a dated clarification when only a detail needs explanation. Routine task updates belong in delivery tracking. If a record contains three unrelated decisions, split it so each can evolve without making the others appear superseded.
Before closing a decision, ask a colleague to explain the behavior from the record alone. If they cannot distinguish saving a draft from publishing it, the log is still missing the most important part. Its purpose is to preserve a usable reason for a specific choice.