The documentation graveyard: why we write docs to forget them

There is a sentence I have learned to brace for, almost always delivered with a small apologetic gesture: 'ignore that page, just ping me in chat.'

That sentence is the verbal headstone of the documentation graveyard. The page is real. The information was once true. The author meant well. The system has moved on without the page, and now the page is, in effect, a polite trap — useful enough to lead a reasonable person somewhere wrong, current enough not to be obviously dangerous, and quietly maintained at the lowest possible level: an occasional commit adding a screenshot, no audits, no owners, and no expectation that anyone will tell the truth on it.

After enough teams, the pattern stops surprising and starts predicting. The shapes differ; the rhyme is uncomfortable. A team loses a week to a documentation sprint. The wiki gets rearranged. READMEs are updated. Architecture diagrams are exported from a tool nobody normally opens. A few runbooks acquire screenshots that will be wrong by the next release. Everyone feels briefly responsible, briefly virtuous, briefly convinced that this time the knowledge will stay captured.

Six weeks later, someone joins the team and follows the onboarding page into a dead end. The service name changed. The deployment command moved. The Slack channel was archived. The architecture diagram shows the queue that was removed during the last incident. The person who knows the truth says, with the same faint embarrassment as every time before, 'ignore that page; ask me instead.'

That is the documentation graveyard. Not a place where documentation is absent, but a place where documentation exists without authority. Pages accumulate. Nobody knows which ones are alive. The search results are full of ghosts. The organisation can point at the wiki and claim knowledge exists, while every experienced engineer knows the real map lives in conversations, memory, and whatever the last person happened to paste into a pull request.

The convenient explanation is that engineers do not like writing documentation. There is some truth in that, but not nearly enough to explain the scale of the failure. The same engineers I watch avoid the wiki will write thorough design notes when they shape an API. They will write minute-by-minute incident timelines while production is still burning. They will write command recipes for themselves, because future pain is a persuasive editor. The problem is not that engineers are constitutionally unable to write. The problem is that organisations ask them to create documentation, then politely decline to treat it as part of the system it describes.

Documentation is usually funded as a clean-up activity. It appears after a release, after a migration, after an audit finding, after a painful onboarding cycle, after someone important asks why there is no runbook. It gets handled in a burst of guilt and then returns to being invisible. The code has owners, tests, reviews, deployment gates, monitoring, and alerts. The documentation has hope.

Hope, I have learned, is a poor maintenance strategy.

The evidence is not subtle

In 2017, GitHub and collaborators ran the Open Source Survey across thousands of respondents from licensed open-source repositories. The result that should still make engineering leaders wince was not obscure: incomplete or outdated documentation was observed by 93% of respondents, yet 60% of contributors said they rarely or never contributed to documentation.¹ That is the whole problem in miniature. Everyone sees the decay. Most people do not work on it.

The survey was about open source, not internal company wikis, but the organisational shape is familiar. Documentation is highly valued by users and newcomers, but it sits in the awkward space between product work and maintenance work. It is important enough to complain about and rarely important enough to prioritise. That makes it structurally vulnerable. Anything that matters but does not have a delivery mechanism becomes somebody else's problem, and 'somebody else' is the most expensive teammate an organisation can hire.

Academic work tells the same story with different instruments. Aghajani and colleagues mined 878 documentation-related artefacts from mailing lists, Stack Overflow discussions, issue trackers, and pull requests, then built a taxonomy of the problems practitioners actually report.² The paper's premise is blunt: documentation has practical value, but its creation and maintenance are often neglected, reducing its quality and usefulness. That sentence should not feel controversial. It should feel indicting.

Tan, Wagner, and Treude approached the problem from another angle in late 2022. They analysed more than 3,000 GitHub projects looking for code element references that survived in documentation after the corresponding source code instances had disappeared.³ Their conclusion was not that some careless projects had stale pages. It was that outdated documentation is pervasive, and one reason it gets out of sync is brutally simple: developers often do not know when a code change has made a document obsolete.

That is the mechanical failure I keep watching teams underestimate. Code changes announce themselves. Tests fail. Types break. Deployments error. Dashboards turn red. Documentation can become false silently. A command can keep sitting on a page years after the binary disappeared. A diagram can keep showing a database nobody queries anymore. A policy can keep describing a review step that teams abandoned six quarters ago. Nothing crashes when the page becomes wrong. People crash into it later, at the worst possible time, while looking for a reason to trust the organisation that told them where to look.

The same fragility appears in the smaller pieces of documentation too. Hata and colleagues studied around 9.6 million links in source code comments and found that almost 10% were dead.⁴ Links are a modest example, but they capture the wider truth. Documentation does not only decay because writers make mistakes. It decays because every dependency it points at keeps moving: code, APIs, teams, product names, external websites, organisational structures, vendor docs, cloud consoles, and human memory. A document is a snapshot of a system. The system keeps walking out of the frame.

Stripe's 2018 Developer Coefficient report is useful here, but not in the way people often want to use it. The report found developers spent 17.3 hours of an average 41.1-hour week on maintenance issues, with 13.5 hours attributed to technical debt and 3.8 hours to bad code.⁵ It does not prove a specific number of hours lost to outdated documentation, and I have learned not to claim otherwise. Treating it that way is exactly the kind of citation laundering that makes documentation worse in the first place. What the report does show is that maintenance drag is not a rounding error. If documentation is part of the system, neglecting it contributes to the same maintenance economy that already eats enormous amounts of developer time.

The research base around documentation cost is weaker than it should be. Zhi and colleagues mapped 69 papers on software documentation cost, benefit, and quality, and found that quality and benefit received far more attention than cost. Only six studies, about 8% of their pool, discussed development or production cost.⁶ Organisations feel the cost of poor documentation every week, but the industry has never become especially good at measuring it. That measurement gap lets documentation decay hide under anecdotes until a migration fails, a customer escalates, or the only person who understands the billing workflow puts in notice on a Friday.

The sprint that creates the graveyard

The documentation sprint is a seductive ritual because it looks like responsibility. It takes an embarrassing backlog of missing knowledge and turns it into visible output. Pages appear. Screenshots appear. Diagrams appear. Leadership sees motion. The team gets to say the docs are 'much better now', and for a brief and pleasant period that might even be true.

Then the product changes. Of course it does. That is the one thing products are reliably good at.

A feature flag is removed. A package is renamed. A deployment flow moves from a shell script to CI. A product manager changes terminology to match the sales deck. A third-party API deprecates a parameter. None of these changes feel like documentation work in the moment. They are 'just' implementation details. The pull request gets reviewed for correctness, test coverage, and rollout risk. The matching documentation change is optional, forgotten, or deferred to 'after launch', which is organisational code for 'never'.

This is why documentation sprints produce graveyards. They create artefacts without creating upkeep. A page born in a sprint has no natural future. It is not attached to an owner. It is not attached to a test. It is not attached to the release process. It is not attached to a deletion policy. It exists because, during one week in May, everyone agreed documentation mattered.

That is not enough, and I cannot stress this enough. I have watched teams repeat the same sprint annually, like a ceremonial cleanse, while every other week of the year the same pattern of decay runs uninterrupted. The pages are perfectly accurate snapshots, taken once a year, of a system that changes weekly. Strictly speaking, that is documentation. Practically speaking, it is taxidermy.

The documentation sprint also creates a dangerous emotional effect. It gives the organisation moral credit for caring about knowledge without requiring structural change. The team did the thing. The backlog is smaller. The VP saw the wiki dashboard. But nobody changed the definition of done. Nobody changed code review checklists. Nobody assigned stewardship. Nobody built a habit of deleting stale pages. Nobody asked whether the documentation was actually discoverable by the people who needed it.

The result is worse than no documentation, in a specific and practical sense. No documentation is honest. It forces people to ask, inspect, trace, and verify. Bad documentation lies with confidence. It sends newcomers down wrong paths. It tells on-call engineers to restart the wrong process. It preserves decisions after the reasoning has changed. It creates the illusion that knowledge transfer happened when all that happened was knowledge storage.

Storage is not transfer. A document nobody trusts is not a document. It is sediment.

Documentation is product surface

Daniele Procida's Diataxis framework is valuable because it starts from the user's need rather than the author's urge to dump information. It separates documentation into four modes: tutorials, how-to guides, reference, and explanation. Canonical publicly adopted the framework in 2021 as a foundation for restructuring technical documentation, describing it as a map and compass for quality.⁷ The useful part is not the labels themselves. The useful part is the insistence that documentation has architecture.

Most internal documentation has no architecture. It has folders. There is a difference, and the difference is most of the problem.

A folder tree organised by team, service, or historical accident does not tell a reader whether a page is teaching, guiding, specifying, or explaining. It does not tell them whether the page is current. It does not tell them whether the page is authoritative or merely a note from a meeting in 2020. It does not tell them what to do when two pages disagree. It is a filing cabinet with search, which is not the same thing as a documentation system, no matter how good the search.

Diataxis is not a magic fix, and treating it as a template migration would miss the point entirely. Its deeper lesson is that documentation belongs to the product. A tutorial has to help a learner succeed. A how-to guide has to get a competent user through a task. Reference has to be reliable. Explanation has to make the system intelligible. Those are product obligations, not clerical chores.

Procida's 2022 principles make the lifecycle explicit: software product documentation has to be created, reviewed, maintained, and expurgated.⁸ That last word matters. Deletion is documentation work. Removing a wrong page is not vandalism. It is maintenance. The graveyard grows because organisations are much better at adding pages than killing them, and most of us were never taught how to kill a page without feeling like we destroyed something precious.

Tom Preston-Werner made a related argument from the other end in 2010 with Readme Driven Development. His advice was to write the README before the code, because writing the interface down forces the author to think through the project before implementation hardens around accidental decisions.⁹ That approach works not because a README is sacred, but because documentation can be design pressure. It can force clarity before code exists, and it can reveal incoherence while change is still cheap.

The tragedy is that organisations often discover this power and then quarantine it to project birth. They write the README first, then let it decay last. They make documentation part of creation but not part of operation. A project that evolves weekly cannot be documented once. It has to be redocumented continuously — not in the sense of rewriting everything, but in the sense of keeping the knowledge surface aligned with the product surface.

This is where the organisational neglect becomes visible. Code is allowed to be living material. Documentation is treated as a snapshot. A snapshot of a moving system becomes false by default. If the system changes and the documentation process does not, the documentation is not slowly drifting. It is being actively abandoned, page by page, by everyone who ships a change without updating the description of it.

The blame-transfer function

There is a phrase I have heard so many times I now wince in advance: 'it's in the wiki.'

It is rarely a helpful sentence. Most of the time it does less knowledge work than blame work. It lets a team or an organisation treat confusion as the reader's fault. The information existed somewhere. The newcomer should have searched better. The on-call engineer should have known which runbook was current. The implementation team should have read the integration guide. The page was there.

This is the bureaucratic afterlife of documentation: a record that protects the organisation from admitting it failed to communicate. It is not there to help the next person succeed. It is there to prove that someone, at some point, typed something.

That is why neglected documentation can coexist quite comfortably with documentation-heavy organisations. A company can have thousands of pages and still have no reliable knowledge system. It can have architecture decision records nobody reads, onboarding portals nobody updates, runbooks that only the newest engineer follows because nobody has told them yet not to, and diagrams that survive purely because deleting them would require admitting they were never maintained.

The graveyard becomes self-protecting. Because the docs are untrusted, people stop using them. Because people stop using them, fewer people notice when they are wrong. Because fewer people notice when they are wrong, they decay further. Eventually the real documentation becomes oral tradition. The wiki remains as a compliance surface, gently misleading anyone foolish enough to take it literally.

This is especially damaging to newcomers. Experienced staff learn the shadow system. They know which pages to ignore, which person to ask, which naming convention predates the rebrand, which runbook only works in staging. New people do not. They treat the official material as official, and the organisation quietly punishes them for believing it. We then describe this as 'a steep learning curve', as if the curve were a feature of the domain rather than the visible shape of our own neglect.

Open-source projects expose the same dynamic publicly. The GitHub survey found documentation helps orient newcomers and that improving it is an impactful contribution, yet the same survey found most contributors rarely or never contribute to it.¹ Newcomers need exactly the thing established contributors are least incentivised to maintain. In companies, the pattern is more expensive because every confused newcomer is on payroll and every private shortcut becomes institutional fragility.

The blame-transfer function also damages incident response, and this is the cost I find hardest to forgive. A runbook that is wrong does not merely fail to help. It consumes time during a state where time is the scarce resource. Someone follows the page, gets unexpected output, asks whether production is different, waits for the one person who remembers the migration, and only then discovers that the documented recovery path belonged to the old queue. The document did not transfer knowledge. It transferred delay, at the worst possible moment, to the people least able to absorb it.

Search does not fix this. Search makes the graveyard searchable.

That distinction matters because so many documentation clean-up projects become search projects in disguise. The organisation buys a better tool, enables full-text indexing, adds tags, imports Google Drive, imports Confluence, imports GitHub, imports Slack, and celebrates that knowledge is now 'discoverable.' Discovery is useful only after authority exists. If a search result returns five pages about deployment, and two are obsolete, one is a half-finished migration note, one is a copy of a vendor guide, and one is the actual current process, search has not solved the knowledge problem. It has made the reader responsible for archaeology.

Archaeology is expensive. It demands context the reader is trying to acquire by reading the documentation in the first place. A senior engineer can open five pages and infer which one is current from service names, command paths, commit dates, and the author list. A newcomer cannot. A support engineer under pressure cannot. An incident commander at 03:00 should not have to. The knowledge system has failed when correctness depends on already knowing the answer.

This is why 'single source of truth' is such an attractive phrase and such a poorly implemented practice. Organisations say it when they mean 'we would prefer people to stop asking us where things are.' A real source of truth is not a place. It is a maintenance relationship. It has ownership, review, and deletion. A wiki page is not a source of truth because it lives in the right folder. It becomes a source of truth only when the organisation makes it more authoritative than memory, more current than chat, and easier to correct than to work around.

The moment a team starts saying 'the docs are wrong, ask the channel', the source of truth has moved. It is no longer the document. It is the social network around the document. That is workable for a small stable team and ruinous for any organisation that expects people to join, leave, rotate, take holidays, respond to incidents, or build systems across team boundaries.

There is also a subtler cost, and it is the one I find easiest to overlook until it has already taken hold: stale documentation teaches cynicism. The first wrong page is an inconvenience. The tenth wrong page is a lesson. Engineers learn that official process cannot be trusted, that onboarding material is ceremonial, that writing things down is mostly a way to satisfy management, and that the real system is hidden in people. Once that belief takes hold, documentation quality collapses faster. People stop fixing pages because nobody reads them. People stop reading pages because nobody fixes them. The graveyard becomes not just a collection of stale artefacts, but a culture.

Ownership beats enthusiasm

The fix is not to ask engineers to care more. Most of the ones I have worked with already care enough to be frustrated. The fix is to make documentation part of the project machinery, the same way tests and deployments are part of the project machinery.

That starts with ownership. Every living document needs an owner or an owning group. Not an author. Authors write pages and move on. Owners are accountable for whether the page remains true, useful, and worth keeping. Ownership does not mean one person does all the writing. It means someone has the authority to review, merge, archive, and say no.

Scope is next. A document should say what kind of thing it is, and what it is not. A runbook is not an architecture essay. A decision record is not a tutorial. A reference page is not a troubleshooting diary. Mixing modes feels efficient for the author and is expensive for the reader. When every page tries to be everything, no page can be trusted for anything.

Proximity to change is the requirement most teams quietly treat as optional and shouldn't. Documentation has to move with the work that invalidates it. If a pull request changes a deployment command, the runbook update belongs in the same change or the same release checklist. If an API response changes, reference material changes with it. If a system is decomposed, the architecture explanation is not a separate hygiene task. It is part of the decomposition. This does not mean every pull request needs a documentation change. It means the question has to be asked where the change happens. Code review routinely asks whether tests are needed. It can ask whether documentation is affected. Release templates routinely ask about rollout plans. They can ask which customer, support, on-call, or onboarding documents are now wrong. The point is not ceremony. The point is coupling knowledge maintenance to the work that creates knowledge debt.

Deletion is the requirement most teams have the hardest time accepting. Every documentation system needs an archive path and a habit of removing obsolete material. Teams fear deletion because some page, somewhere, might contain one useful paragraph. That fear is how graveyards grow. If a page has one useful paragraph, rescue the paragraph and delete the corpse. Search quality is a product feature. Every obsolete result makes the next search worse.

Testing matters, even when the tests are manual. Runbooks should be exercised. Onboarding guides should be followed by actual newcomers and revised from their failures. Commands in tutorials should be copy-pasted into disposable environments. Links should be checked. Diagrams should be reviewed against the production reality, not against the architecture the team wishes it had. A document that cannot survive contact with use is not documentation. It is a draft that someone forgot to mark as draft.

Visible retirement is the quiet partner of deletion. A documentation system needs a way to say 'this used to be true.' That can be an archive folder, a banner, a redirect, a deletion policy, or a commit history. The exact mechanism matters less than the principle: old knowledge should not masquerade as current knowledge. Organisations are often afraid to delete because deletion feels like losing context. In practice, leaving obsolete pages in the main path loses more context, because it forces readers to distrust everything around them.

Prioritisation is the last and least glamorous requirement. Documentation work should be planned where the knowledge risk lives. A low-level implementation detail used by two people may not need a polished guide. A payment reconciliation process, an on-call recovery path, an authentication integration, a data deletion policy, or a customer-impacting API absolutely does. Treating all documentation as equally important creates the same failure as treating all bugs as equally urgent. The team drowns, gives up, and the graveyard expands.

This is where documentation governance has to stay practical. The goal is not to document every thought in the building. The goal is to protect the knowledge that, if missing or wrong, slows delivery, increases risk, blocks onboarding, harms customers, or concentrates operational power in one person's head. Some knowledge belongs in code. Some belongs in tests. Some belongs in product behaviour. Some belongs in runbooks, references, explanations, and tutorials. The work is choosing deliberately, not dumping everything into a wiki and hoping future readers can sort it out.

There is a cultural requirement underneath all of this, and it is the one most worth fighting for. Documentation work has to count. If teams are rewarded only for shipping features, they will ship features and let knowledge rot. If roadmaps treat documentation as overhead, engineers will treat it as overhead too. If managers praise heroic debugging but stay quiet about the runbook that would have prevented the same midnight page next time, they have declared which behaviour matters. The organisation gets the documentation system it funds, not the documentation system it wishes for.

There is no mystery in the funding model. If a roadmap allocates time for implementation, testing, rollout, support preparation, and customer communication, but not documentation, the organisation has decided documentation is unpaid labour. It may still be performed by conscientious people in the margins. That is not a process. That is extraction. Eventually those people stop donating the invisible work, or they leave, and the organisation discovers that the knowledge layer was being subsidised by personal guilt — and that personal guilt, as it turns out, is not on the renewal contract.

The healthier version is far less dramatic. Documentation becomes ordinary. It appears in estimates when it matters. It appears in review when it changes. It appears in incident follow-up when a runbook failed. It appears in onboarding feedback when a newcomer gets stuck. It appears in deprecation work when a system is retired. Nobody needs a campaign, a slogan, or a quarterly docs day. The work happens because the project cannot be considered done while its knowledge surface is false.

There is a reason the documentation graveyard feels inevitable. It is the natural result of a system that produces change faster than it maintains understanding. It requires no malice. No one needs to hate writing. No one needs to be negligent in the dramatic sense. The graveyard forms whenever documentation lacks ownership, review, lifecycle, and deletion.

That also means it is not inevitable.

A team can decide that a runbook is part of the service. A platform group can decide that reference material changes with APIs. A product organisation can decide that user-facing documentation is part of feature acceptance. An engineering manager can decide that deleting stale pages is delivery work. A CTO can decide that knowledge maintenance belongs in planning capacity rather than in the guilty scraps left after launch.

None of these decisions is glamorous. They will not produce a beautiful wiki dashboard overnight. They will not create the satisfying theatrical burst of a documentation sprint. They will, however, prevent the quiet accumulation of falsehoods that makes every future change slower, every incident longer, and every newcomer's first month more expensive than it had any right to be.

The documentation graveyard is not a writing problem. It is a maintenance problem, an ownership problem, and ultimately a management problem. Organisations know how to keep important systems alive. They assign owners. They create checks. They review changes. They monitor failure. They remove dead paths. They make the work visible. If documentation is not receiving that treatment, the organisation has already made a decision. It has decided that the knowledge layer is less important than the code layer, even though every developer, operator, support engineer, customer, and newcomer experiences the system through both.

The next time a team proposes a documentation sprint, the useful question is not 'what pages will we write?' The useful question is 'what will keep those pages true after we stop paying attention?' If nobody can answer that, the sprint is not documentation work. It is landscaping for a cemetery.

The docs will look better for a while. Then the product will move. The pages will stay behind. And six weeks later, a new engineer will follow the map into the old world and learn the first unofficial rule of the project: ask someone who was there.

That is not knowledge management. It is organisational amnesia with a search bar. And the search bar, at this point, is barely an excuse.

---

Footnotes

1. GitHub. (2017). 'Open Source Survey.' GitHub and collaborators. https://opensourcesurvey.org/2017/ ↩ ↩²

2. Aghajani, E., Nagy, C., Vega-Marquez, O. L., Linares-Vasquez, M., Moreno, L., Bavota, G., & Lanza, M. (2019). 'Software Documentation Issues Unveiled.' 2019 IEEE/ACM 41st International Conference on Software Engineering (ICSE). https://2019.icse-conferences.org/details/icse-2019-Technical-Papers/49/Software-Documentation-Issues-Unveiled ↩

3. Tan, W. S., Wagner, M., & Treude, C. (2022). 'Detecting Outdated Code Element References in Software Repository Documentation.' arXiv. https://arxiv.org/abs/2212.01479 ↩

4. Hata, H., Treude, C., Kula, R. G., & Ishio, T. (2019). '9.6 Million Links in Source Code Comments: Purpose, Evolution, and Decay.' arXiv. https://arxiv.org/abs/1901.07440 ↩

5. Stripe. (2018). 'The Developer Coefficient.' Stripe. https://stripe.com/files/reports/the-developer-coefficient.pdf ↩

6. Zhi, J., Garousi-Yusifoglu, V., Sun, B., Garousi, G., Shahnewaz, S., & Ruhe, G. (2015). 'Cost, benefits and quality of software development documentation: A systematic mapping.' Journal of Systems and Software, 99, 175-198. https://doi.org/10.1016/j.jss.2014.09.042 ↩

7. Procida, D. (2021). 'Diataxis, a new foundation for Canonical documentation.' Canonical. https://canonical.com/blog/diataxis-a-new-foundation-for-canonical-documentation ↩

8. Procida, D. (2022). 'Twelve principles of documentation.' Daniele Procida. https://vurt.eu/articles/principles-documentation/ ↩

9. Preston-Werner, T. (2010). 'Readme Driven Development.' Tom Preston-Werner. https://tom.preston-werner.com/2010/08/23/readme-driven-development.html ↩