When to adopt docs as code and when not to
We wrote this overview to help documentation leads and engineering managers decide whether the docs-as-code workflow fits their team. If you're making the case for the migration, or deciding whether to approve it, this page contains the conversation you want to be having.
The short answer
Docs as code is a workflow, not a product: documentation lives in git as plain text, changes are reviewed in pull requests, and an automated pipeline builds and publishes the site. That workflow has a sweet spot.
Adopt docs as code when:
- Your product ships versions, and readers need docs for the version they run, not just the latest one.
- Documentation changes should land in the same review cycle as the code changes that make them necessary. Ideally, your documentation changes should arrive in the same pull request.
- Your contributors already live in git, or your writers are willing to learn a workflow in exchange for owning their toolchain.
- A wiki has burned you: stale pages nobody owns, no review, no history you can trust, and an export problem when you want to leave.
Think twice when:
- Most of your contributors are non-technical, and no one can staff the on-ramp. Git is learnable, but someone has to teach it, review early contributions patiently, and own the tooling.
- Your documentation is a handful of internal pages that change weekly and die monthly. A wiki's zero-friction editing genuinely wins there.
- You need WYSIWYG collaboration with live cursors as the primary authoring experience. That's a different product category, and pretending otherwise frustrates everyone.
What the workflow actually buys you
- Review before publish. Docs changes get the same scrutiny as code: a diff, a reviewer, a conversation, an approval. Quality no longer depends on who last edited.
- Docs that track releases. When version 2.1 branches, its docs branch with it. Fixes backport the way code does, with a cherry-pick, not an afternoon of copy-paste archaeology.
- Automation. The pipeline that builds the site can also lint prose,
validate cross-references, and reject a pull request that breaks them.
Antora resolves every
xref:at build time, so link rot becomes a build failure instead of a 404 a customer finds. - No exit problem. Your documentation is a directory of text files in repositories you own. Changing site generators is a migration; changing wiki vendors is an excavation.
Why AsciiDoc rather than Markdown
Markdown is the default answer, and for a README it's the right one. For a documentation system, AsciiDoc earns its keep in three places:
- Reuse is built in.
include::partial$prereqs.adoc[]pulls one maintained snippet into twenty pages. Markdown needs preprocessor bolt-ons to do the same, and every bolt-on is another dialect. - Single-sourcing through attributes. Define
:product-name:or:min-node-version:once and reference it everywhere; change it at release time in one place. Conditional text (ifdef::cloud[]) comes from the same mechanism. - Semantics the toolchain can check. Admonitions, callouts on code lines, validated cross-references, and one specification instead of a flavor per renderer.
The cost is real but small: AsciiDoc is less universally known than Markdown, so expect a week of "how do I make a table again?" questions. The reference and a good pull-request template absorb most of them.
What adoption costs
- Tooling ownership (moderate): someone maintains the playbook repository, the CI pipeline, and the UI bundle. Budget a few days for setup and an hour or two a month after that.
- Contributor skill (the honest cost): engineers contribute happily from day one. Writers coming from Confluence need a Git on-ramp to teach them how to branch, edit, push, and open a pull request. In our experience, that's two weeks of discomfort, then it becomes muscle memory; the failure mode is skipping the investment and quietly recreating the wiki in Google Docs.
- Migration (pay once): converting existing content is mechanical (Pandoc gets you 80% of the way), but editing it into Diátaxis-shaped pages is where the time goes. Migrate the docs readers actually open; let the rest die in the archive.
- Infrastructure (low): the output is a static site. Any object store, Pages product, or web server can host it.
What you're really comparing
| Alternative | When the alternative wins | When docs as code wins |
|---|---|---|
| Wiki (Confluence, Notion) | Internal notes, meeting pages, content with a shelf life of weeks. Zero-friction editing matters more than review. | Product docs with versions, review requirements, or any lifespan. Wikis have no diff, no branch, and no honest export. |
| Hosted docs SaaS (GitBook, ReadMe) | Small team, no CI culture, you want a polished site this week and accept the vendor's editor and pricing. | You need multi-repo content, real versioning from branches, CI-enforced link checking, or an exit path you control. |
| Markdown + general-purpose SSG (MkDocs, Docusaurus) | Single repository, single version, JavaScript-ecosystem team that wants React components in pages. | Several repositories or versions feeding one site, heavy content reuse, attribute-driven single-sourcing. This is the problem Antora was built for. |
| Doc comments only (OpenAPI, ExDoc, Javadoc) | API reference generated from source is non-negotiable, so keep it. | Reference generated from code covers one Diátaxis quadrant. Tutorials, how-tos, and explanations still need a home. |
A pragmatic adoption path
If you're not sure, run the cheap experiment:
- Pick one product area with a real versioning problem and migrate only its docs: one component repository, one playbook, one CI job. The tutorial is deliberately that shape.
- Route two or three release cycles through it. Watch pull-request review actually catch doc bugs, and watch a backported fix land in the old version's docs the same day.
- Expand component by component, or stop. Because each component is just a directory in a repository you already own, stopping costs nothing.
Teams that run the experiment rarely roll it back — not because the tools are flawless, but because "the docs are wrong and nobody noticed" stops being a weekly event.
Next steps
- Your first Antora site: working software in 45 minutes.
- How Antora assembles a site: the model, for the architect who wants to know what they're buying.