SOP: Living doc vs changelog for tracking changes

SOP: Living doc vs changelog for tracking changes

Run this whenever you need people to know what changed in a process or product.

Stage 1 — Identify the reader's need (owner: doc owner)
☐ Do readers need current truth, or the history of how it got there?
☐ Is the audience operators (current state) or downstream consumers (deltas)?

Stage 2 — Choose
☐ Living doc: always shows the current state, edited in place. Use as the single source of truth for how things work now. Cost: history is lost unless you keep version snapshots.
☐ Changelog: append-only list of dated changes. Use when consumers must react to each delta (API changes, policy updates). Cost: never shows the full current picture at a glance.

Stage 3 — Run both (owner: doc owner)
☐ Living doc holds the present; changelog records every meaningful edit with date and author.
☐ Living doc links to the changelog; each changelog entry links the section it changed.
☐ Done-when: a reader can answer both "what's true now" and "what changed."

Trigger: a process or spec keeps changing. Done-when: both layers exist and cross-link.

Save this. Run it every time.