A developer-tools company in JetBrains' mould has a 60-page architecture document, last substantially revised 14 months ago, referenced in a customer security questionnaire and in an ISO certification scope statement. Engineers do not read it. Sequence the migration to decision records plus one page per service, keeping the audit story intact at every step.

Why this is a migration and not a rewrite

The document has two readers with incompatible needs. Engineers need the answer to one question at the moment they are changing something. Auditors need evidence that a described control exists and is operating. A single artefact serving both decays towards the audit reader, because that is the reader who complains. Deleting it to serve engineers breaks a certification scope statement, which is a commercial problem, not a documentation one.

So the sequence has to keep the audit surface addressable while the engineering surface is rebuilt.

The sequence

1. Inventory what the document is load-bearing for. Walk the certification scope statement and the security questionnaire and list every claim that cites it. This is usually 4 to 10 paragraphs out of 60 pages. Reversible, costs a day, and it tells you what cannot be deleted.

2. Freeze the document and mark it historical. Add a dated header: this describes the architecture as of the given date, and current structure lives elsewhere. A document explicitly labelled historical stops lying, which is most of the harm it was doing, and the label changes nothing for the auditor as long as the cited claims are also maintained elsewhere.

3. Extract the load-bearing claims into a control document the audit reader owns. Short, one section per control, each naming the mechanism and where the evidence is produced. This is now the artefact the questionnaire cites. Reversible: the frozen document still exists.

4. Start decision records for new decisions only. Do not backfill. One record per decision from today, in the repository that the decision affects, with the context and the alternatives. The backfill is the step that kills these migrations, because it is weeks of work producing documents about decisions nobody is currently questioning.

5. Write one page per service, generated where possible. What it does, what it depends on, its SLO, how to deploy it, what pages you at 03:00. The parts that can be derived — dependencies, owners, endpoints — should be generated from the service catalogue, because a hand-maintained dependency list is wrong within a quarter.

6. Backfill decision records on demand only. When someone asks why a decision was made, write the record then, with the frozen document as the source. Demand-driven backfill converges on the decisions that matter and never touches the rest.

7. Update the certification scope statement at the next recertification, pointing at the control document rather than the frozen one. This is the point of no return: after it, the frozen document has no external reader and can be archived.

Where it can diverge, and how you would know

Between steps 3 and 7 the claim exists in two places. If the control document is edited and the frozen one is not, an auditor reading the old citation sees a stale answer. Guard it by making the control document the only editable copy from step 3 onward and by checking, at the next internal audit, that every questionnaire citation resolves to it.

The second divergence is the service pages drifting. The guard is generation plus one check in the pipeline: a service with no page, or a page whose declared dependencies do not match the catalogue, fails the build.

How long it really takes

Steps 1 to 3 are about two weeks of one person's time. Steps 4 and 5 are continuous and start paying back in a month. Step 7 waits for the recertification calendar, which can be nine months away, and that wait is the honest answer to "when is this done" — the engineering benefit arrives long before the audit surface is cleaned up.

When not to do this at all

If the document is read by nobody and cited by nobody, delete it and write the service pages. The whole sequence above exists to protect external citations. No citations, no migration.