Templates and habits that keep docs useful when the team that wrote them moves on. The hardest problems on an engineering team are rarely technical. This post is about the habits and small agreements that let a group of people ship good work without burning out.
Why this matters
We changed one thing at a time and wrote down why. That record turned out to be the most useful part, because six months later nobody remembered the original problem.
# Decision: <short title>
**Date:** 2024-05-01
**Status:** accepted
**Owners:** @platform-team
## Context
What problem are we solving, and why now?
## Decision
What did we choose?
## Consequences
What gets easier, what gets harder, and when do we revisit this?
What we changed
Reviews got faster once we agreed on what they are for: catching bugs and sharing knowledge. Style debates moved to the linter, and architecture debates moved to a short design note before any code was written.
- Agree on what code review is for.
- Write decisions down where people will find them.
- Automate style arguments away.
- Pair new people with a named mentor.
How it went
Remote work made all of this more deliberate. Decisions that used to happen in a hallway now happen in writing, which is slower in the moment and much faster for everyone who joins later.
As always, the examples are simplified to fit on a page. The production version has more error handling and logging, but the shape of the code is the same.
Questions, corrections, and war stories are welcome in the comments. Several of our best follow-up posts started as a reader pointing out something we had missed.
Before you ship this
A template nobody fills in is worse than no template. Keep it to four headings and make the first one about the problem, not the solution.
Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
Martin Fowler, Refactoring, 1999
Wrapping up
If you try this on your own project, start with one page or one service rather than the whole codebase. A small experiment gives you real numbers to argue with, and it is easy to roll back if the idea does not fit.
This finally clicked for me after reading the docs three times.
Our accessibility audit flagged exactly this last month. I wish I had read this first.
Bookmarked. The code sample alone saved me an afternoon.
Tried it on a side project over the weekend and it worked first time, which never happens.
The quote in the middle is doing a lot of work here, and it earns it.