Name the Pain Before the Tool: Fast, Correct, Easy, Pick Two
Pick the doc tool after you name the pain. Docs go stale for three reasons: machine, process, and people. AI fixes only the first one. The team fixes the rest.
When a team talks about docs, the first question is often: “Which wiki (Notion, Obsidian, Confluence), or which AI plugin?”
I think that order is backward. Name the problem first. Then choose the tool. Do not let today’s popular tool decide what your problem is.
Fast, correct, easy: you get two
| Approach | You get | You lose |
|---|---|---|
| Built from code (FastAPI) | fast and correct | only “what”, never “why” |
| Written by hand in a wiki | easy to start | slow to update, less correct every week |
| Written by AI for each pull request | fast and close to the code | costs money, and a person still must review it |
How long can a doc be wrong? It depends on the damage
| Doc | If it is wrong | Update it |
|---|---|---|
| Onboarding page | a new team member asks someone | every few weeks |
| Architecture overview | a design starts from a wrong picture | every release |
| Runbook | an incident gets worse | every change |
One rule for all docs is too strict for some and too loose for others.
Three causes, three fixes, and AI fixes only one
Break down the cycle from How a Doc Goes Stale, and you find three causes.
| Cause | Kind | Example | What fixes it |
|---|---|---|---|
| The doc stops matching the code | machine | The Makefile is gone, but the README still says make ... | AI or a pipeline |
| Nothing asks for an update, no owner | process | A PRD written at kickoff, never updated after the scope changed | a named owner and a schedule |
| No reward | people | A decision made in team chat, and nobody wrote an ADR | team culture, not a tool |
This is the easiest mistake to make in the AI era. AI is very good at the first cause, so we think the doc problem is solved. But AI cannot touch the second and third causes.
The process cause can go to fixed reminders. See Keep Docs Alive: Three Reminders, One Direction.
Even then, some wrong docs will get through. So you need a recovery step. The real question for your team is: how fast must you fix a wrong doc?
AI can keep docs in step with the code. Only the team can make people want to write them.
References
Related: revisit How a Doc Goes Stale, see the three reminders, or go back to the series overview: Docs in the AI Era.