Somewhere in your company there's an engineer who knows why the payments service has a retry policy that looks insane. They know because they were on call the night it earned that policy — the night a downstream provider went flaky for six hours and the naive retry logic turned a partial outage into a self-inflicted DDoS. That knowledge is in one person's head. When they leave, it leaves with them.
Unless someone wrote it down.
Documentation nobody reads vs. writing people remember
Let's be honest about internal documentation: most of it is a write-only medium. Wikis go to die. The architecture decision record that was supposed to capture why we chose the message queue gets written six months after the decision, by someone reconstructing it from Slack threads. The runbook covers the happy path and three of the sad ones; the fourth sad one is the one that pages you.
But there's a different kind of internal writing, and it works. It's the incident retrospective that reads like a story instead of a template. It's the "here's what I learned migrating the auth service" post that an engineer writes because they need to think it through, and then it turns out half the org needed to read it. It's the decision record written before the decision, while the tradeoffs are still alive and contested, instead of after, when everyone's just justifying what already happened.
The difference isn't format. It's honesty. The writing that gets read is the writing that tells the truth about what happened — including the parts where someone made a bad call at 3 AM and the system survived anyway.
Incident lore is an asset
Every company has incident lore: the outage everyone references by name, the deploy that became a verb. "Don't pull a Jenkins on the database migration." That lore is doing real work — it's compressed experience, transmitted orally, and it shapes behavior more than any policy document.
The problem with oral tradition is that it doesn't scale and it doesn't survive turnover. The new hire in the satellite office doesn't know what "pulling a Jenkins" means. The lore becomes an in-joke instead of a lesson.
Writing it down fixes this, but only if the writing captures the actual story. A good incident write-up has a narrative arc: here's what we believed, here's what happened, here's what we believe now. It names the surprise. The surprise is the valuable part — it's the thing nobody's mental model predicted, which means it's the thing everyone's mental model needs to absorb.
The best internal incident writing I've seen reads less like a report and more like a field note from someone who was there. Because it is.
Decision records, written when they matter
Architecture decision records have a timing problem. Written after the fact, they're archaeology — interesting, maybe, but nobody's mind is changed by them. The doc exists to make the decision better. The fact that it also becomes a record is a bonus. Teams that get this backwards — writing the ADR to satisfy a process, after the decision is already made — get the worst of both worlds: the overhead of documentation with none of the clarity.
I've started treating decision docs as discussion documents with a shelf life, not as monuments. The doc exists to make the decision better. The fact that it also becomes a record is a bonus. Teams that get this backwards — writing the ADR to satisfy a process, after the decision is already made — get the worst of both worlds: the overhead of documentation with none of the clarity.
Write in public (internally)
Here's the part that makes people nervous: the best internal writing is visible. Not in a private doc shared with three people, but somewhere the whole engineering org can stumble across it. The junior engineer who reads a senior's migration post-mortem learns more in twenty minutes than in a month of ticket work. The team in another timezone avoids a mistake because someone wrote down the mistake they made.
Yes, this requires a culture where writing honestly about failures doesn't get you punished. That's a leadership problem, not a tooling problem. No wiki platform ever fixed a blame culture.
But if you have even a pocket of that culture — one team that writes real postmortems, one engineer who documents the weird retry policy and why — protect it. Feed it. That person is doing the most undervalued work in your organization: turning experience into something that outlives the people who had it.
The payments service retry policy looks insane until you know the story. Write down the story.