Greenbox has 8,000 subscribers, 28 people, and some of the best documentation any startup has ever produced. Architecture Decision Records. Decision tables. Onboarding guides. The documentation was the team’s institutional memory. Six months later, it’s institutional fiction.
Nina has been at Greenbox for two months. She joined the Brisbane squad, went through the onboarding checklist, paired with Ravi for her first fortnight, and submitted her first PR on day three. By all measures, the onboarding worked. Nina is sharp, thorough, and trusts the documentation, which is exactly the problem.
On a Tuesday morning in early December, Nina picks up a story: add a retry mechanism to the billing service for failed charges. She does what every good developer does. She reads the relevant ADR first.
ADR-001 is the billing system’s foundational document. It captures the insight that Priya first surfaced during the Event Storming session: billing can’t happen at signup because box contents aren’t known until after supply matching. The ADR explains that Greenbox charges customers on delivery day, Thursday, after box contents are finalised on Tuesday evening. The reasoning is thorough: variable box contents mean variable costs, so charging at delivery aligns billing with actual value.
Nina reads it carefully. She designs the retry mechanism around the delivery-day assumption: if a Thursday charge fails, retry on Friday and Saturday. If it still fails by Sunday, pause the subscription and notify the customer.
She implements it. The code is clean, the tests pass, the PR gets reviewed by a Brisbane colleague who also references ADR-001 during the review. It ships on Wednesday.
On Thursday, 280 Melbourne subscribers are charged twice.
What changed
Three months ago, the billing team in Perth changed the charge timing. The original design (charge on delivery day) worked when Greenbox had one city and one delivery day. But with three cities on different delivery schedules, the charge-on-delivery approach created a rolling billing window that made revenue reporting a nightmare. The finance team couldn’t close the books until Saturday because Brisbane charges arrived later than Perth charges.
Tom and Ravi redesigned the billing flow. Charges now happen on dispatch day, Wednesday, when the warehouse confirms the box is leaving. This gives finance a single cut-off point across all cities. The change was discussed in a Slack thread, implemented in a PR, and deployed without incident.
Nobody updated ADR-001.
The ADR still says charges happen on Thursday. Nina’s retry logic assumes Thursday is day one. But Thursday is actually day two; the charge already happened on Wednesday. The retry logic triggers a second charge on what it thinks is the retry window, but the payment gateway sees it as a new charge for a new day.
Two hundred and eighty double charges. An average of $47 each. $13,160 in incorrect billing.
Sam’s inbox fills up in forty minutes.
The retrospective
The incident retro happens on Friday afternoon. The whole team, all squads, video call. Tom runs it.
“Root cause: Nina followed ADR-001, which describes the billing system as it was three months ago, not as it is today. The ADR was accurate when written. It hasn’t been updated since the billing change.”
Nina is quiet. She’s two months in. She followed the documentation, did the correct thing, and broke production. The feeling is familiar to anyone who’s been the new person, the dread of having caused a problem you didn’t know was possible.
Tom sees it. “This isn’t Nina’s fault. If I’d picked up this story, I’d have known ADR-001 was stale because I was in the room when we changed it. But the whole point of ADRs is that you shouldn’t need to have been in the room. That’s why we wrote them.”
Priya has been going through the other ADRs during the meeting. Her face says everything before she speaks.
“I’ve checked all twelve ADRs we wrote after Charlotte’s workshop. Five of them are still accurate. Three are partially accurate: the core decision is correct but the details have drifted. Four are wrong. They describe a system that no longer exists.”
She pulls up the decision tables next. “The substitution tables are in better shape because we update them when we add new produce. But I found two tables where the conditions reference a field name that was renamed in September. The tests still pass because the tests were updated, but the documentation tables weren’t.”
The numbers settle over the room.
Accurate
Drifted
Wrong
Current
Stale references
“We spent a week writing these,” Priya says. “A genuinely useful week. Everyone agreed they were valuable. And then nobody looked at them again.”
Why documentation rots
Documentation rot isn’t a failure of discipline; it’s a natural consequence of how software teams work.
Code changes constantly. Every PR modifies the system. Some changes are small: a renamed field, an updated dependency. Some are large, like a redesigned billing flow. Each change potentially invalidates one or more documents. But the PR review process checks whether the code is correct. It doesn’t check whether the documentation is still correct.
The problem compounds over time. One stale document is a nuisance. Ten stale documents undermine the team’s trust in all documentation. Once people learn that the docs might be wrong, they stop reading them. And then you’ve lost both the documentation and the habit of consulting it.
This is worse than having no documentation at all. No documentation creates a known gap, so people know they need to ask. Stale documentation creates false confidence: people think they know, and they’re wrong.
Tom puts it bluntly: “ADR-001 didn’t just fail to help Nina. It actively harmed her. She would have been better off asking in Slack. At least then someone would have corrected the assumption in real time.”
Living documents vs historical records
Lee joins the retro by video. He’s been listening.
“Not every document needs to be a living document. Some documents are historical records, they were true when they were written, and their value is in recording what was known at that time.”
“How do you tell the difference?” Nina asks. It’s the first time she’s spoken.
“A living document describes the current state of something. ‘This is how billing works.’ It needs to be maintained because the thing it describes changes. A historical record describes a moment in time. ‘In March, we decided to charge on delivery day because of variable box contents.’ It never needs updating because March didn’t change.”
The distinction clicks for the room.
ADR-001 was written as a living document (“this is how the billing system works”) but it should have been a historical record: “in March, we decided to charge on delivery day.” The decision was real. The reasoning was sound. The context was accurate at the time. When the billing system changed, the team should have written ADR-014: “We changed from delivery-day billing to dispatch-day billing because of multi-city revenue reporting.” ADR-001 gets its status changed to “Superseded by ADR-014.” The old reasoning is preserved. The new reasoning is current.
“The ADR format already has this,” Charlotte adds. “The status field. Accepted, superseded, deprecated. We just never changed any statuses.”
Tom scrolls through the ADRs. Every single one says “Accepted.” None have ever been superseded or deprecated.
“We treated them as write-once documents. We wrote them, felt good about them, and moved on. But the system didn’t move on.”
The ownership problem
Priya raises a deeper issue. “Every ADR has an author. None of them have an owner.”
“What’s the difference?”
“The author is who wrote it. The owner is who’s responsible for keeping it current. When the billing system changed, who was responsible for updating ADR-001?”
Nobody answers, because the answer is nobody.
Charlotte nods. “This is the most common failure mode. Documentation without ownership is documentation that will rot. Not might. Will. It’s not a question of discipline or team culture. It’s structural. If nobody’s job includes ‘keep this document accurate,’ then nobody will do it.”
She draws an analogy. “You wouldn’t write a test suite and then never run it again. Tests only have value because you run them on every change. Documentation is the same, it only has value if someone checks it against reality.”
The team pushes back. “We can’t assign an owner to every document. We have fifty documents across three squads.”
“You don’t need a person per document. You need a rule: the team that owns the system owns the documentation for that system. When Perth changes the billing flow, Perth is responsible for updating the billing ADRs. Not as an afterthought. As part of the definition of done.”
Ravi speaks up. “We already have ‘update tests’ in our definition of done. We could add ‘update docs.’”
“Specifically: check whether the change affects any ADR, decision table, or onboarding guide. If it does, update or flag. If you’re not sure, flag it anyway. A false alarm costs five minutes. A missed update costs a production incident.”
The review cadence
Lee suggests something practical. “You don’t need to review every document every week. You need a cadence that matches how fast things change.”
He proposes a quarterly documentation review. Same cadence as the Wardley Map review. Once a quarter, each squad takes an hour to go through their documents:
- Is this still accurate?
- Has the system changed since this was last verified?
- Should this be superseded by a new document?
- Should this be deprecated?
Each document gets a “last verified” date. A simple timestamp at the top: Last verified: Q3 2026. When someone reads a document and sees a verification date that’s more than one quarter old, they know to check with the team before trusting it.
“It’s the documentation equivalent of a use-by date,” Lee says. “Not expired, just worth checking.”
Documentation as code
Tom has a practical suggestion. “The ADRs currently live in a shared document. The decision tables live in a spreadsheet. Both are separate from the code they describe. What if we moved them into the repo?”
Documentation-as-code means storing documents alongside the code, in the same repository, subject to the same version control. When someone submits a PR that changes the billing system, the reviewer can check whether the ADR in the same repo needs updating. The documentation appears in the diff. It’s visible.
“Right now,” Tom continues, “the billing code and the billing ADR live in completely different places. I can change the code without ever seeing the ADR. If the ADR is a markdown file in the same directory as the billing code, it’s in my face. I have to consciously choose to ignore it.”
The team agrees. Over the next week, they move all ADRs into a /docs/adrs/ directory in the main repository. Decision tables move into /docs/decisions/ alongside the bounded context they describe. The onboarding guide moves into /docs/onboarding/.
It’s not a silver bullet. Moving documents into the repo doesn’t automatically keep them current. But it closes the distance between code and documentation. When someone reviews a PR that touches billing, the billing ADR is one directory above. The reviewer can glance at it. The author can update it in the same PR.
Update, deprecate, or delete
The team sorts the twelve ADRs.
Five are still accurate. They get a “Last verified: Q3 2026” header and no other changes.
Three have drifted. The core decision is correct, but details have changed. Tom updates the details and adds a “Revision history” section at the bottom: what changed, when, and why.
Four are wrong. Two of those describe decisions that have been explicitly reversed. They get superseded: new ADRs are written for the current decisions, and the old ones get “Status: Superseded by ADR-014” (and so on). The other two describe systems that no longer exist. They get “Status: Deprecated” and a note explaining what replaced them.
The decision tables get a similar pass. Priya updates the two with stale field references. She adds a comment at the top of each table: Last verified: Q3 2026. Owner: Perth squad.
Nina helps with the audit. She’s in a unique position. As the person who was burned by stale documentation, she has a visceral understanding of what “accurate” needs to mean. She reads each document with the eyes of someone who might build something based on it. Several times, she flags ambiguities that the original authors don’t notice because they carry context that isn’t on the page.
“This ADR says the subscription service ‘handles’ cancellation,” Nina says. “Does that mean it processes the cancellation, or that it sends a message to another service that processes it?”
“The latter,” Ravi says.
“Then it should say that. Because ‘handles’ means something different to someone who doesn’t know the architecture.”
The tension
The retrospective surfaces a tension that doesn’t have a clean resolution.
Writing documentation takes time. Maintaining documentation takes more time. And a team under delivery pressure will always deprioritise maintenance, because the cost of stale documentation is invisible until something breaks.
“We’re asking people to do more work,” Tom says. “Review ADRs quarterly. Update docs in every PR. Add verification dates. On top of everything else.”
Charlotte is honest. “Yes. It’s more work. The question is whether it’s less work than the alternative.”
The alternative is what just happened. A developer trusted stale documentation. A feature shipped based on wrong assumptions. Two hundred and eighty customers were charged twice. Sam spent two days processing refunds. Nina spent a day debugging. The team spent an afternoon in a retro. Total cost: roughly four person-days plus $13,160 in temporary overcharges and an unknown amount of customer trust.
“The quarterly review is four hours per squad. Sixteen hours total. The incident cost about thirty-two hours total. One stale ADR cost twice what maintaining all of them would have.”
“One incident,” Tom counters. “If we go a year without another, the maintenance is wasted.”
“You won’t go a year without another. The system changes every week. The documentation falls behind every week. The only question is when the gap becomes a problem, and who’s holding the bag when it does.”
What Lee said
After the retro, Lee calls Tom.
“How’s Nina?”
“Embarrassed. I told her it wasn’t her fault.”
“It genuinely wasn’t. But she’ll carry it for a while. The new person who broke production. Even if nobody else blames her.”
“I know.”
Lee is quiet for a moment. “The documentation problem isn’t really about documentation. It’s about the gap between how fast a system changes and how fast the team’s understanding of that system catches up. Documentation is one way to close that gap. Pair programming is another. ADRs are another. But no single mechanism is enough, because the system is always moving.”
“So what’s the answer?”
“Multiple mechanisms, overlapping. Documentation for the things that can be written down. Pairing for the things that can’t. Reviews for catching drift. And a culture where updating a document is considered real work, not busywork.”
“That last one’s the hardest.”
“It always is.”
Six weeks later
The quarterly documentation review happens in late January. Each squad takes ninety minutes. They go through every ADR, every decision table, every onboarding guide section that belongs to their bounded contexts.
Perth finds two ADRs that need updates, one for a logging change, one for a new caching layer. Tom writes the updates during the review session.
Melbourne finds one decision table with a new produce item that was added to the substitution engine but not to the documentation. Anika updates it and adds a note to the PR template: “If this PR changes substitution logic, update the relevant decision table.”
Brisbane finds everything current. Nina, who runs the review, reports this with a quiet satisfaction that the rest of the team notices.
The “last verified” dates get updated. The documents are accurate, for now. They’ll drift again. The system will change, and someone will forget to update a document, and the gap will reopen. That’s the nature of documentation in a living system.
The team has accepted this. Documentation isn’t a state you achieve; it’s a practice you maintain. Like the continuous discovery cadence, like the sprint retrospectives, like the quarterly planning. The discipline isn’t in getting it correct once. It’s in checking, again and again, whether it’s still correct.
Nina adds one line to the onboarding guide. Under the section about ADRs, between “read the relevant ADRs before starting work on a bounded context” and “ask your buddy if anything is unclear”:
Check the “last verified” date. If it’s more than three months old, verify with the team before building on it.
It’s the kind of line that only someone who learned the hard way would think to write.