Docs & Code Guide

Keep design docs useful after shipping: harvest the final state, mark the rest historical

A design doc is a proposal, written to win an argument at a moment in time. Once the project ships, editing it to match reality quietly rewrites the record of what was decided and why. So the maintenance question is not how to keep design docs updated, it is what to extract from them when they stop being the plan: harvest the final state into current-state documentation, and mark the proposal as history.

Try it free
7 min readFor engineering teams whose wiki search returns three contradictory designs for the same system

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

194/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

A design doc is frozen at decision time, on purpose

The value of a design doc after shipping is exactly its staleness: it records what the team believed, which options were on the table, and why the tradeoffs fell the way they did. Editing it later to match the built system destroys that record while producing a bad current-state doc, because proposal structure, goals, alternatives, rollout plan, is the wrong shape for describing a running system.

This is the same principle that makes architecture decision records append-only: you supersede a decision with a new one, you do not edit the old record. The practice for ADRs is covered in keep ADRs up to date; design docs deserve the identical discipline with one addition, the harvest.

The harvest step nobody schedules

Between the design doc and the shipped system there is always a delta: the queue that got swapped mid-build, the phase two that never happened, the cache added during the launch incident. That delta is precisely the content current-state documentation needs and precisely what nobody writes down, because no ceremony exists at the moment the project ships.

The fix is putting one item on the launch checklist: harvest the design. Thirty minutes, done by the person who wrote the doc, producing three outputs: the current-state page describing what actually runs, the diagram of the built system, and the superseded banner on the proposal. Teams that skip this accumulate wikis where every page is a proposal and no page says what exists, which is how documentation debt compounds fastest.

Mark superseded docs so search stops lying

The reader who finds a two-year-old design doc through search has no way to know whether it describes the present. A status banner at the top of the doc fixes that in one edit, and the discipline is cheap enough to apply retroactively to a whole wiki in an afternoon. The banner answers three questions: did this ship, where is the current description, and why is this doc still here.

> **Status: shipped, March 2026. Historical document.**
> This is the proposal as decided in November 2025, kept for the
> reasoning and the alternatives we rejected. The system as it runs
> today, including the changes made during the build, is described in
> [Checkout architecture](../architecture/checkout.md), which carries
> the live diagram.

Design docs, ADRs and current-state docs: three shapes, three lifecycles

The taxonomy that keeps a wiki sane: a design doc proposes a change and freezes at decision time; an ADR records one decision and is superseded, never edited; a current-state doc describes the running system and is the only one of the three that gets continuous updates. Most documentation confusion traces to one document trying to be two of these at once, usually a design doc drafted into service as the permanent description of a system it no longer matches.

Keeping the current-state docs actually current is its own discipline with its own tooling, which the rest of this cluster covers; the design doc's job ends when it hands its final state over.

FAQ

Should design docs be updated after the project ships?

No. A design doc is a decision-time record, and editing it to match the built system erases the history of what was proposed and why. Instead, harvest it: extract the final architecture into a current-state doc and diagram, add a superseded banner pointing there, and leave the proposal frozen as the record of the decision.

What is the difference between a design doc and documentation?

A design doc is a proposal: it argues for a change, freezes when the decision is made, and its value afterward is historical. Documentation in the current-state sense describes the system as it runs and must be continuously updated. Confusing the two produces wikis full of proposals and no reliable description of the present.

What should happen to old design docs?

Keep them, banner them, link them. Delete nothing: the reasoning and rejected alternatives answer future "why is it built this way" questions. Add a status banner saying whether it shipped and where the current description lives, and link it to the current-state page and diagram harvested from it. A wiki-wide banner pass takes an afternoon and permanently fixes search.

What is the harvest step for a design doc?

A launch-checklist item, about thirty minutes, done when the project ships: write the current-state page describing what actually got built including deviations from the plan, create or update the diagram of the shipped system, and add the superseded banner to the proposal. It converts the design effort into durable documentation at the one moment the delta is still remembered.

Who should do the harvest and when?

The design doc author, at ship time, because they are the only person who still holds the full delta between plan and build in their head. A quarter later that knowledge is gone and the harvest becomes archaeology. Making it a launch-checklist item is what ensures it happens while the memory is fresh.