Every team I’ve joined – Decloud, a fintech startup, a large consumer platform – had a Confluence graveyard. Hundreds of pages. Nobody reading any of them. The onboarding guide references a deploy process that changed eight months ago. The architecture doc describes a system that was replaced last quarter. A new engineer follows the getting-started page and hits a dead end on step three.
This isn’t a tooling problem. Notion, Confluence, GitHub wikis, markdown in the repo – the tool doesn’t matter if nobody owns the content.
Why Nobody Reads Your Docs
It’s always the same reasons:
They can’t find them. Docs live in three different places, none of them searchable in the way engineers actually search. Slack threads become the real documentation, and Slack threads expire.
They don’t trust them. One bad experience with an outdated runbook and the engineer stops checking docs entirely. Rational behavior. If the doc might be wrong, it’s faster to ask a human.
They’re written for the wrong audience. A tutorial mixed with reference material mixed with architectural rationale. The reader can’t tell what kind of doc they’re looking at, so they close the tab.
The Fix Is Boring
Separate your doc types. This is the Divio framework and it works:
- Tutorials – learning-oriented, for newcomers. “Follow these steps and you’ll have a running service.”
- How-to guides – task-oriented, for people who already know the basics. “How to rotate database credentials.”
- Explanations – understanding-oriented. “Why we chose event sourcing for the payment system.”
- Reference – information-oriented. API specs, config options, environment variables.
When you mix these, you get a doc that’s too long for lookup and too shallow for learning. Pick one purpose per page.
Structure That Earns Trust
Readers scan. They decide in five seconds whether to keep reading. Help them:
- State the purpose and audience in the first line.
- List prerequisites up front.
- One action per step. Expected output after each step.
- A troubleshooting section for the two or three things that always go wrong.
- An owner name and a “last verified” date.
That last one matters more than people think. A doc with “Last verified: 2022-06-01 by @law” tells the reader someone is paying attention. A doc with no date and no owner tells the reader nobody is.
Ownership Is the Whole Game
At a large consumer platform, we started requiring that every doc in the engineering wiki had exactly one owner. Not a team. A person. That person got a quarterly reminder to verify or archive.
The result: we deleted about 40% of our docs in the first quarter. That was a good thing. The remaining 60% were accurate, and engineers started trusting them again.
No owner means no maintenance. No maintenance means the doc will lie to you. A lying doc is worse than no doc.
Docs as Code
Put docs in the repo. Require doc updates in PRs when behavior changes. Run link checks in CI. This isn’t a radical idea – it’s the same review process you already use for code. If the deploy process changes and the PR doesn’t update the runbook, the reviewer should block it.
I know this sounds heavy. It’s lighter than answering the same question in Slack every week.
Stop Measuring Page Views
Page views tell you nothing useful. A doc that gets 500 views might be getting 500 confused visitors who leave after ten seconds.
Better signals: How many support questions come in on topics you have documented? How long does onboarding take? How often do incidents get extended because the runbook was wrong?
If the answer to “where is the doc for X” is always “ask Sarah,” your docs have failed regardless of how many pages you have.
The Short Version
Delete the docs nobody maintains. Give every surviving doc an owner. Separate tutorials from reference from how-to guides. Put them in the repo and review them like code.
Documentation is a product. Ship it or kill it.