proto[docs]

The Architecture Documentation Map

Which architecture documents to write, who reads each one and which ones you can skip.

One Document, Too Many Readers

Most architecture documentation goes unread because it tries to serve everyone at once. Each reader shows up with one question & has to dig for the answer.

You have probably seen this page. It’s called “Architecture Overview.” It opens with the history of the move off the monolith, turns into setup steps halfway down, lists every environment variable in a table & ends with a diagram from two reorgs ago.

I’ve worked at far too many places that have “An Architecture Diagram” that outlines how half of their systems looked 2 years ago. Documents like that are worse than useless; they actively misinform. Nobody trusts them, so the real answers end up living in someone’s head.

I get it, writing documentation is tedious. It’s a thankless job & seems to be out of date the moment you click save. But we have all been on the receiving end of bad documentation. Documents that try to say everything, but end up saying nothing.

In this guide we are going to dive into what makes good documentation by answering two simple questions: who is reading & what they are trying to do right now.

The Four Modes

We are actually going to start by answering the second question. And to do that, we are going to look at the Diátaxis framework by Daniele Procida. It sorts documentation into four modes based on what the reader needs at that moment.

TutorialLearning by doing.“Walk me through it.”
How-to guideGetting a job done.“How do I roll this back?”
ExplanationUnderstanding why.“Why is it built this way?”
ReferenceLooking something up.“What does this service own?”
Figure 1. The Diátaxis modes. The top row is for doing & the bottom row is for knowing. The left column serves someone learning; the right serves someone at work.

Architecture documentation mostly lives in the bottom row. Diagrams are reference & decision records are explanation. I think that’s the right home for most of it, but it leaves out the tutorials & how-tos that new & on-call engineers reach for first.

A document should answer one kind of question for one kind of reader. If it answers two, it should be two documents.

Who Reads Architecture Documentation?

Five kinds of reader show up. Each brings a different question & a different amount of time.

One person can wear several of these hats. Go by the question they bring rather than their job title.

ReaderThe question they bringWhen they show up
New engineer“How does this fit together, & how do I make my first change without breaking it?”First two to six weeks. Reads a lot, in order.
Maintaining engineer“What does this service depend on, & why did we build it this way?”Before a change or a review. Reads one section & leaves.
On-call / operations“What is broken, who owns it & what do I do right now?”During an incident. Has minutes.
Product & leadership“What do we have, who owns it & what does it stop us from doing?”Planning, budgeting, due diligence. Wants one page.
Security & compliance“Where does sensitive data go, & what protects it?”Audits, reviews, vendor questionnaires. Reads everything & checks it.

Different Slices

It’s tempting to write one long document with the simple part on top & the detail at the bottom. That breaks down fast. A security reviewer needs more detail on data flows than a new engineer does, & none of the setup steps. Each reader needs their own slice of the system.

The Map

Five readers across four modes gives you twenty cells. Fifteen of them are worth writing. Here is what goes in each one.

Rows are readers. Columns are what they are trying to do.

ReaderTutorialHow-toReferenceExplanation
New engineerLaptop to first merged change, end to endAdd an endpoint, add a service, run one test suiteGlossary, container diagram, repo mapSystem context & the handful of decisions that shaped it
Maintaining engineerSkipRelease, roll back, rotate a secret, migrate dataAPI contracts, data model, config keys, dependenciesDecision log & known trade-offs
On-call / operationsOne guided incident drill, run onceA runbook per alertDependency map, owners, dashboards, SLOsSkip
Product & leadershipSkipSkipSystem landscape: what exists & who owns itOne-page context diagram with its risks
Security & complianceSkipHow to pull audit evidenceData flows, trust boundaries, data classesThreat model & the controls chosen against it

Write It Once & Leave the Gaps

The context diagram serves new engineers & leadership. Draw it once & link to it from both rows; if you keep two copies, one is already wrong. The skipped cells are just as deliberate. Every document costs maintenance for as long as it exists, so spend that on readers you actually have.

How Do You Use the Map?

You can audit your current documentation against the map in an afternoon. Keeping it accurate takes a habit.

The Audit

  1. Cross out the rows you don’t have. A ten-person startup with no compliance requirement can drop the last row for now.
  2. For each remaining cell, find the document that answers it today. Write its link in the cell or leave it blank.
  3. Look for links that show up in more than one column. Those documents mix modes. Split them.
  4. Rank the blank cells by how often someone asks that question in chat or in meetings. Write the top three first.
  5. Give every document an owner. The ones without an owner go stale first.

Run the audit with the people who field the questions in chat. They already know which cells are empty.

System Changes Trigger Document Changes

Documentation rarely goes stale from neglect alone. Something specific changes & nobody connects that change to the page. For each document on the map you can name the event that makes it wrong.

DocumentGoes stale whenWho notices first
Context diagramA system is added, retired or starts talking to a new third partyA new hire, or an auditor
Container diagramA service is split, merged or renamedThe next engineer to onboard
RunbooksAn alert, threshold or piece of infrastructure changesOn-call, mid-incident
API referenceA contract changesThe consuming team, in production
Data flowsA new data store or vendor receives sensitive dataThe security review, late
Setup tutorialThe toolchain or a dependency version changesThe next new hire, on day one

If you can name the event that makes a document wrong, you can catch it when it happens. Use this list as a springboard to create your own.

If you would rather not rewrite these by hand when the system changes, proto[docs] generates the diagrams & references from what is running & refreshes them as it changes.

Resources

The frameworks this guide leans on, if you want to go deeper.