Docs-as-Code or WordPress? How to Choose a Documentation Stack

Choose docs-as-code when the people writing the documentation are the people writing the software. Choose a CMS when the people writing the documentation are not. Almost every other argument in this debate is downstream of that one question: not which tool is better, but who is expected to edit.

This is a comparison written from both sides. Both approaches produce excellent documentation, and both produce abandoned documentation, usually for reasons that were predictable on day one.

What is docs-as-code?

Docs-as-code means treating documentation like source: Markdown files in the repository, changes reviewed in pull requests, and a static site generator turning them into HTML in CI. Tools in this family include Docusaurus, MkDocs, Sphinx, Hugo, Astro Starlight and VitePress.

Its real advantage is not Markdown or Git in the abstract. It is that documentation changes travel in the same pull request as the code change that made them necessary, and a reviewer sees both. Nothing else keeps docs current as reliably as that.

A minimal pipeline is genuinely small:

name: docs
on:
  push:
    branches: [main]
    paths: ["docs/**"]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci && npm run docs:build
      - run: npx linkinator ./build --recurse
      - uses: actions/deploy-pages@v4

That file, a generator, and a theme is the whole stack. It also has to be maintained by somebody who understands all three.

What does a CMS give you instead?

A content management system moves the editing surface into a browser. There is no clone, no branch, no build. Somebody in support notices a wrong screenshot, fixes it, and it is live in ninety seconds.

That is a smaller-sounding advantage than it is. Documentation decays because the person who spots the error is rarely the person willing to open a pull request, and every step between noticing and fixing loses a proportion of the people who noticed.

The trade is that you inherit a platform: updates, plugins, hosting, backups. It is a well-understood kind of maintenance, but it does not go away.

Docs-as-code and a CMS, compared honestly

Notice that the last row is the same failure described twice. Each approach breaks at the point where its central assumption stops holding.

Which should you choose?

Some rules that hold up in practice:

• Your docs are an API reference generated from source. Docs-as-code, without hesitation. Generated output belongs in the pipeline that generates it.
• Your writers are technical writers, not engineers. A CMS. Asking a writing team to resolve merge conflicts is a tax you pay forever.
• Support and success staff should be able to fix things. A CMS. This is the single strongest signal there is.
• Documentation must be versioned alongside releases. Docs-as-code makes this natural; a CMS needs a deliberate versioning scheme.
• You also need marketing pages, a blog and a contact form on the same domain. A CMS, unless you enjoy running two stacks.
• Nobody owns the build. A CMS. An unowned static pipeline is a broken deploy waiting for the day the person who set it up is on holiday.

The hybrid nobody talks about

These are not mutually exclusive. A common and underrated arrangement: authors draft in Markdown in the repository, and the Markdown is imported into a CMS that owns the reading experience: search, navigation, theming, redirects.

Engineers keep writing in the editor they already have. Everyone else gets a browser. You give up the guarantee that docs ship with the code, so it works best when the import runs on release rather than by hand.

The costs nobody quotes you

• Static site generators churn. Major versions arrive with breaking config changes, and a docs site is exactly the kind of project nobody budgets time to upgrade.
• Search is not free. A hosted search service is a subscription and a third-party dependency; a self-hosted index is code you own.
• CMS plugin sprawl is real. Every plugin is an update, a vulnerability surface, and a thing that can conflict.
• Migration in either direction is a week you did not plan for. Weigh it once, properly, rather than twice, badly.

A recommendation

If your documentation is written by engineers, for engineers, from a repository they already work in: docs-as-code, and put the effort into search and navigation, because that is where static sites are usually weakest.

If anyone outside engineering is expected to contribute, and in most companies past a certain size they are, pick the CMS and spend the saved effort tying documentation to your release process, because that is where a CMS is weakest.

Doku is built for the second case, with the first case in mind: documentation lives in a plugin-owned post type so it survives a theme change, and a Markdown importer takes a folder of files and turns them into real editable blocks rather than a wall of HTML.