Document Every System the Same Way
What a shared template gives your readers & writers, & how to keep it small enough to use.
Every Team Writes It Differently
Ask five teams to document their services & you get five different documents. Each one makes sense to the person who wrote it.
One team leads with a diagram. Another opens with setup steps & tucks the dependencies under a heading called “Misc.” A third never says who owns the thing. On its own, each page is fine. Side by side, they’re hard to use.
The reader pays for it. Every page is a new layout to learn before they find the answer they came for, & on-call doesn’t have time to learn a layout.
Readers Know Where to Look
Give every system the same sections in the same order & readers stop searching. They go straight to the part they need.
After the second page, a reader knows the owner is always at the top & dependencies are always third. That holds for a service they’ve never touched. It holds for people outside engineering too, who read your documentation least often & gain the most from not relearning it.
The Architecture Documentation Map covers which documents to write & who reads each one. A template decides what goes inside them, so every system answers the same questions in the same place.
Gaps Show Up on Their Own
Freeform documentation hides what’s missing. A template turns every missing answer into an empty slot you can see.
Without a template, nobody can tell whether billing has no runbook or keeps it somewhere else. With one, the gap is an empty section under a heading everyone recognizes.
The same structure makes documentation checkable. When every page has an Owner section, listing the systems with no owner takes a minute instead of a read through every page.
Writers Start Faster
The blank page is the hardest part of writing documentation. A template replaces it with a list of questions.
With a template, the writer doesn’t have to decide what to cover. They answer the questions that are already there, in the order they’re already in.
Reviews get easier too. A reviewer checks each section against its question, instead of debating what the page should contain. New teams get the house style for free on their first service.
Keep the Template Small
A template can fail the same way a freeform page does, by trying to cover everything.
Every section you add is a section someone fills in for every system, for as long as it exists. Make too many required & writers start typing “N/A” to get through it, & readers learn to skip whole pages. Keep a short core every system answers & add sections only where they apply.
Start with the questions people already ask in chat. If nobody asks it, it doesn’t need a section yet.
Resources
Further reading on documentation structure & templates.
- arc42: a template for architecture documentation
- Diátaxis: the four documentation modes, by Daniele Procida
- The C4 model: context, container & component diagrams, by Simon Brown
- Documenting Architecture Decisions: the original ADR post, by Michael Nygard
- The Architecture Documentation Map: which documents to write & who reads each one