“Docs as Code” Is the Wrong Abstraction

The documentation world has a consensus answer to the question “how should we manage docs?”: docs as code.

Put your docs in Git. Write them in Markdown. Review them with PRs. Build them with CI. Treat them like code.

It sounds right. It feels modern. And it solves exactly one problem: versioning.

Everything else — accuracy, drift, completeness, freshness — docs-as-code doesn’t touch. It gives you a better workflow for content that still goes stale the moment it’s merged.

The industry optimized for the wrong thing.

What Docs-as-Code Actually Solves

Let’s be fair. Before docs-as-code, documentation lived in wikis. Confluence pages. Word documents attached to Jira tickets. SharePoint sites nobody visited.

Docs-as-code fixed real problems:

• Version control. Docs in Git have history. You can see who changed what and when.
• Review process. PRs mean someone looks at documentation changes before they ship.
• Co-location. Docs live next to the code they describe. No context-switching to a separate tool.
• Automation. CI can build, lint, and deploy docs automatically.

These are genuine improvements. If your docs are currently in a wiki, moving them to a repo is a massive upgrade.

But here’s what docs-as-code doesn’t solve: it doesn’t check whether your documentation is accurate.

A Markdown file in a Git repo can be just as wrong as a Confluence page. The PR review can miss the fact that the amount field changed from integer to string. The CI pipeline can build and deploy documentation that’s beautifully formatted and factually incorrect.

Docs-as-code gives you better tooling for content. It doesn’t give you validation.

The Assumption Behind Docs-as-Code

The docs-as-code movement is built on an assumption: documentation is a content problem. If we can make the content workflow as good as the code workflow, documentation will be better.

This assumption is wrong.

Documentation isn’t a content problem. It’s a synchronization problem. The content exists. The question is whether it matches the code it describes.

Think about it from first principles. What makes documentation useful? Not the formatting. Not the search. Not the beautiful developer portal. Accuracy. Documentation is useful when it tells the truth about the code.

Docs-as-code optimizes for content workflow. It doesn’t optimize for accuracy. Those are different problems.

A team can have a perfect docs-as-code setup — Markdown in Git, PRs reviewed, CI deployed — and still have 40% of their API docs be wrong within a quarter. The workflow is great. The docs are still drifting.

What the AI Era Changes

For humans, docs-as-code was a reasonable compromise. Humans can compensate for some inaccuracy. We read around gaps. We check the source code when the docs don’t make sense. We ask a colleague.

AI agents can’t do any of that.

When an AI coding assistant reads your documentation, it doesn’t have a fallback. It reads the docs, trusts the docs, and generates code based on the docs. If the docs are wrong, the code is wrong. There’s no “let me check the source code” step. There’s no “this doesn’t make sense, let me ask someone.”

This means the accuracy bar for documentation has gone up. Not because humans got more demanding, but because a new class of reader has zero tolerance for inaccuracy.

And here’s the thing: docs-as-code doesn’t raise the accuracy bar. It raises the workflow bar. You can have a perfectly reviewed, CI-deployed Markdown file that’s still wrong about the amount field.

The Validation Gap

The gap in the docs-as-code approach is validation. There’s no step in the pipeline that checks whether the documentation matches the code.

Here’s a typical docs-as-code workflow:

1. Developer writes code.
2. Developer writes docs (or doesn’t).
3. PR is opened. Reviewer checks code. Maybe checks docs.
4. CI builds the docs site.
5. Docs are deployed.

At no point does anyone — or any system — compare the documentation to the code. The PR reviewer is checking for writing quality, not factual accuracy. The CI pipeline is checking that the build succeeds, not that the content is correct.

The workflow assumes that if the docs were written correctly at some point, they stay correct. They don’t. Every code change is a chance for the docs to drift. And the docs-as-code workflow has no mechanism to catch it.

What Docs-as-Validation Looks Like

If docs-as-code optimizes for content workflow, docs-as-validation optimizes for accuracy.

A docs-as-validation workflow looks like this:

1. Developer writes code.
2. Developer writes docs (or doesn’t).
3. PR is opened. Reviewer checks code.
4. Automated system compares docs to code. Every endpoint, field, type, and example is checked against the actual codebase.
5. Drift is flagged in the PR. Not as a suggestion — as a build failure.
6. Developer fixes the docs (or the code). CI passes. The merge goes through.

The difference is step 4. That’s the validation layer. It’s the thing that docs-as-code doesn’t have.

This isn’t a theoretical workflow. This is what boringdocs does. It sits between your code and your docs and continuously checks that they agree. Not at publish time. On every commit. In every PR.

Why the Industry Hasn’t Moved Yet

If validation is the missing piece, why hasn’t the industry adopted it?

Three reasons:

1. Docs-as-code was “good enough” for humans. Before AI agents, the cost of inaccurate docs was bounded. One confused developer at a time. A support ticket here, a failed integration there. Bad, but not catastrophic. Docs-as-code improved the workflow enough that the accuracy problem felt secondary.

2. Validation is harder than versioning. Putting docs in Git is easy. Building a system that reads code, reads docs, and compares them semantically is hard. It requires parsing multiple languages, understanding code structure, and mapping it to documentation. The tooling hasn’t existed until recently.

3. The AI agent audience is new. Two years ago, your documentation had one audience: humans. Today it has two. The second audience is less forgiving, but most teams haven’t internalized what that means for their documentation infrastructure.

The Contrarian Take

Here’s where we’ll lose some friends: docs-as-code is a local maximum.

It’s better than wikis. It’s better than Confluence. It’s better than Word documents. But it’s not the destination. It’s a stepping stone.

The teams that treat docs-as-code as the final answer will have better workflows and the same accuracy problems. The teams that move to docs-as-validation will have both.

This doesn’t mean you should stop putting docs in Git. Keep your Markdown files. Keep your PRs. Keep your CI pipeline. Just add a validation step that checks whether the content is telling the truth.

Docs-as-code solved the workflow problem. Docs-as-validation solves the accuracy problem. You need both, but only one of them actually keeps your docs honest.

The Bottom Line

The documentation industry optimized for content workflow. That was the right problem to solve a decade ago. It’s not the right problem to solve now.

The right problem — the one that matters in the AI era — is accuracy. Not “are our docs well-written?” but “are our docs telling the truth?”

Docs-as-code doesn’t answer that question. Docs-as-validation does.

Stop optimizing for content workflow. Start optimizing for accuracy. The AI agents reading your docs will thank you. Eventually.

---

Docs-as-code solved versioning. Docs-as-validation solves accuracy. Join the waitlist — boringdocs is the validation layer that keeps your docs in sync with your code, continuously. Because your Markdown files can be perfectly reviewed and still wrong.