Your team maintains a 90-page architecture document that is always out of date and nobody reads. What should replace it?

Diagnose why it is unread

Ninety pages serving no identified reader is the usual cause. It was written to be comprehensive rather than for a specific person answering a specific question, so nobody's question is answered quickly and everyone stops looking.

The staleness follows from the same thing: a document nobody reads is a document nobody corrects.

Replace it with four artifacts, each with a reader

A context diagram and a container diagram, one page each. The first for anyone orienting; the second for engineers and reviewers. These change rarely, which is why they stay accurate.

Decision records, in the repository, written when decisions are made. These answer "why is it like this?", which is the question the ninety pages was mostly failing to answer.

A README per service covering how to run it, how to deploy it, who owns it, and where its dashboards are. Reviewed in the same pull request as the code, which is what keeps it current.

Runbooks, attached to alerts, for whoever is on call.

The rule that keeps them current

Documentation that lives next to the code and is reviewed in the same pull request stays accurate. Documentation in a separate system is updated when someone remembers, which is why the ninety pages drifted.

What to do with the existing document

Mine it for decision records, then delete it. Keeping it as a reference while maintaining the replacements produces two sources that disagree, and the stale one will be the one somebody finds.

What is genuinely lost

Some organisations require a formal document for governance or contractual reasons. Where that is true, generate it from the maintained artifacts at the point it is needed rather than maintaining it continuously — which is a smaller and more honest commitment.