The Case Against Docs-as-Code
Docs-as-code fixed review and version control but left the hardest parts untouched. Where the workflow breaks down, and what actually has to change.
Docs-as-code was a genuinely good idea and it won completely. Documentation lives in the repository, in markdown, reviewed in pull requests, deployed by CI. Nobody argues for a separate wiki any more. The problem is that having won, it gets treated as a solved problem, and the specific thing it solved was narrower than the credit it receives.
It fixed the plumbing. It did nothing about whether anybody writes anything.
What it genuinely fixed
Credit where it is due, because the before state was worse than people remember.
Version control means documentation can branch with the feature it describes and merge when the feature merges. Review means a second person sees it. CI means publishing is not a person remembering to click something. Diffing means you can see what changed and when. Those are real, and going back to a wiki that nobody can review and everybody can silently edit would be a regression.
If your documentation is not in version control, put it there. Everything below assumes you already have.
The three things it never touched
Intent. Docs-as-code makes writing documentation as easy as writing code. It does not make anyone want to. The pull request template with the unticked "documentation updated" checkbox is the most honest artefact in the entire industry - the workflow is right there, frictionless, and the box stays empty because the incentive did not change. Making a task easier does not schedule it.
Coverage. The workflow tells you what exists and says nothing about what is missing. A repository with forty markdown files and no article on the feature everybody asks about looks exactly like a repository with complete documentation. There is no diff for the page that was never written, and no CI check has ever failed because a customer could not find something.
Decay. This is the serious one. Docs-as-code puts prose next to code and then provides no mechanism whatsoever for noticing when they diverge. Rename a setting in the code and the markdown paragraph two directories away describing the old name does not fail to compile, does not fail a test, does not appear in any report. It sits there being wrong, in version control, reviewed, deployed, with a green build.
The workflow gives documentation the appearance of engineering rigour without any of the feedback loops that make engineering rigour work. That is a worse position than an unreviewed wiki in one specific way: it inspires confidence it has not earned.
The audience problem underneath
There is a deeper mismatch that the tooling debate tends to obscure.
Docs-as-code optimises for the writer being an engineer with the repository open. That is correct for architecture notes, runbooks and API references - documents whose reader is also an engineer, whose vocabulary is the codebase's vocabulary, and which genuinely should version alongside the code.
It is a poor fit for user-facing documentation, where the writer needs to think in the customer's language rather than the codebase's, where screenshots matter, and where the reader will never see the repository. Putting those files in /docs does not make them good; it just files them somewhere convenient for the person least likely to write them well.
Most teams run both kinds through one workflow because one workflow is simpler, and then wonder why the user-facing half is thin.
I am not telling you to stop
I am arguing against treating docs-as-code as sufficient, not against using it, and the distinction matters because the alternatives are mostly worse.
For a developer tool whose users are engineers reading on GitHub, docs-as-code is close to ideal and none of my complaints land. The audience mismatch disappears when the audience is you.
The decay criticism is also not unique to this workflow - documentation in every system drifts. What is fair to say is that the repository is the one place where the signal exists, sitting unused in the diff, which makes not acting on it a more visible waste than it is elsewhere.
And I have an obvious interest here. I build a product that derives documentation from code rather than storing it beside code, so treat the argument on its merits and not on my say-so.
What to change on Monday
Keep the repository, the review and the CI.
Then add the thing the workflow never had: something that notices when a merged change contradicts a published page, and puts it in front of a human. Until that exists, the unticked checkbox is telling you the truth.
About the Author
Simon Moxon has been building SaaS companies since 2009. He's scaled teams to 20+ people, hit £2m ARR, and learned most of the lessons the hard way. Now he's building SupportPages.io - help docs that write themselves when you ship code. He writes about what's changed in SaaS and what hasn't.