NexusBloomVisit Website →
← Back to blog

Docs as Code: What It Is and How to Start

November 9, 2026
Docs as Code: What It Is and How to Start

Docs as code means writing and maintaining documentation with the same tools and workflows you use for software: plain-text files, Git, pull requests, automated checks and a CI pipeline that publishes on merge. The Write the Docs community describes it as using issue trackers, version control, plain-text markup, code reviews and automated tests for docs. This guide explains how the workflow runs, which tools teams use, where it strains, and how a solo developer or small team can start this week.

Nexusbloom
Keep Tool Logic in One Place
Nexusbloom lets developers define a JSON Schema manifest and pure function once, then serve them across web, CLI, API, and AI agent tools.
Visit Nexusbloom

TL;DR

  • Docs as code stores documentation in the repository, reviews it in pull requests, tests it in CI and publishes it automatically.
  • It works best when developers write the docs and the audience is technical. It strains with non-technical authors, many languages or heavy content reuse.
  • A small team can start with one docs/ folder, Markdown, a static site generator and free hosting. Add linters later.
  • Docs still drift when nobody is forced to update them, so add a check that ties doc claims to the code.
  • The same idea extends to machine-readable tool definitions: one schema, one function, many surfaces.

Table of Contents

What docs as code actually means

The core idea is simple: documentation is treated as a build artifact of a source file, not as a separate document living in a wiki or word processor. The UK Home Office engineering standards say the docs should preferably sit in the same repositories as the source code, written in Markdown, reStructuredText or AsciiDoc, and that writers follow the same workflow as the development team, documenting features as developers finish them.

Compare that with the traditional approach. FreeCodeCamp's walkthrough contrasts Word documents and PDFs, where changes are tracked by hand, with docs stored in Git, written in lightweight markup and updated alongside the code.

Traditional docsDocs as code
Where it livesWiki, word processor, shared driveRepository, next to the code
Change trackingManual or page historyGit commits and diffs
ReviewAd hoc commentsPull requests
Quality checksHuman proofreadingAutomated link, style and build checks
PublishingManual export or uploadCI on merge

The name "docs like code" most likely comes from Anne Gentle's book of the same title, according to this explainer. You will see both phrases, and they mean the same thing in practice.

How the workflow runs, step by step

Most teams converge on the same loop. Sourcegraph describes it as write in plain text in the repository, review by pull request, test in CI, publish automatically on merge.

  1. Write. Edit a Markdown file on a branch, in the same change as the code it describes. TechTarget notes that drafting docs concurrently with development is where the efficiency comes from.
  2. Review. Open a pull request. A subject matter expert checks the facts. In bigger teams a technical writer checks the user task, structure, terminology and clarity, and the machine checks whatever can be expressed as a deterministic rule, as TechWriters.org lays out.
  3. Test. CI runs on every pull request. An academic documentation maintenance guide lists broken-link checks, language linting and confirmation that the site builds.
  4. Publish. On merge, the pipeline builds the site and deploys it. No one exports a PDF by hand.

What the automated checks look like in practice

One company engineering blog, Talon.One, describes linting Markdown, testing English against a style guide with Vale, and checking output for broken links and accessibility issues, all run through GitHub Actions and git hooks. Their review is two steps: experts validate content, then another writer checks efficiency and clarity.

The point is not the specific tools. It is that every rule you can write down becomes a check no one has to remember.

The tool stack

You do not need all of this. Here is the typical stack, drawing on TechTarget's overview:

  • Authoring: Markdown or AsciiDoc in an editor such as VS Code or IntelliJ.
  • Site generation: static site generators such as MkDocs, Jekyll, Hugo and Docusaurus.
  • Version control and hosting: Git on GitHub, Bitbucket or GitLab.
  • Automation: GitHub Actions, Jenkins or GitLab CI/CD.
  • Quality tools: Vale and MarkdownLint for prose and formatting, plus OpenAPI and Swagger for API reference.

For day-to-day Git work, our Git cheat sheet is handy for writers who are new to branches and commits. If your docs include configuration examples, the .env validator and JSON formatter help you keep samples correct before they land in a pull request.

Topologies: where the docs live

Docs repositories are not all laid out the same way. Passo.uno describes four topologies: sidecar, orthogonal, federated and specialized, where the docs site pulls data from code repositories on demand. Its advice is to pick the pattern that helps you climb your current priorities, not the most elaborate one.

What you gain

Stack Builders lists collaboration, version control, automation, consistency, faster feedback and scalability. Three benefits matter most in practice.

Developers already know the tools. No one has to learn a separate documentation system. A doc fix can be made in the same pull request as the code change, which Typemill's authors call perhaps the most important cultural advantage.

You get a full history. Every change is a commit you can read, blame or revert.

You can enforce documentation. Write the Docs points out that you can block merging of new features that lack documentation, which encourages developers to write while the feature is fresh.

Keeping docs from drifting anyway

There is a catch. Sourcegraph's author argues that the biggest driver of fresh docs is that the person changing the code is right there to change the doc, but putting docs in the repo makes them easy to update without forcing anyone to. The fix he recommends is a verification step that checks doc claims against the code before drift ships.

That idea leads directly to the next section: the best way to stop drift is to stop writing the same fact twice.

Where docs as code strains, and how teams adapt

Docs as code is not a universal answer, and the people who use it every day say so. Knowing the pressure points lets you plan for them.

  • Who writes. Sourcegraph calls it a strong default for developer-facing docs written by developers, and a weaker default for marketing or end-user content written by non-engineers. A web-based editing layer can lower the barrier.
  • Writers' tooling. ClickHelp notes a high barrier for writers used to specialized authoring tools, no visual editing for non-technical teams, and scaling trouble with thousands of topics, many versions and multilingual content.
  • Build maintenance. Docsio warns that a forked theme or a broken plugin can leave the docs site fragile when the one engineer who understood the build leaves. Keep the toolchain boring and documented.
  • Reuse and translation. Author-it argues that reuse across products means copy-pasting Markdown, which drifts, and that translation lacks a change-tracking workflow.
  • Ritual over value. TechWriters.org advises choosing the minimum sufficient level for each stage, and skipping a pull request when author and publisher are the same person and risk is low.

Topicary lists four conditions under which docs as code remains the right call: a developer audience with engineers as contributors, single-audience content, one product, version and language, and a small team of one to three writers. If that describes you, you are in the sweet spot.

Getting started as a solo developer or small team

For one to five people, Unmarkdown recommends a deliberately small setup:

  1. Create one docs/ directory in your main repository.
  2. Write Markdown files with frontmatter.
  3. Generate the site with VitePress or Starlight.
  4. Host on GitHub Pages or Vercel.
  5. Skip CI linting at first. Add Vale and markdownlint when you pass about 20 pages.
  6. Put the documentation update in the same pull request that changes public-facing behavior.

That last rule does most of the work. Add a pull request template with one checkbox, "docs updated or not needed", and you have a lightweight merge gate on day one.

A sensible order for adding checks

Start with a build that fails on error, because a broken build is the loudest signal. Then add a link checker. Then add prose linting once you have a style you want to enforce. Resist adding all three before you have ten pages.

Three documentation checks in recommended order

Docs as code for APIs and AI agent tools

The hardest drift problem is not prose. It is the same logic described in several places: a web form, a CLI command, an API endpoint and an AI agent tool, each with its own description of inputs and behavior.

Machine-readable descriptions already exist for this. The Model Context Protocol lets servers expose tools to language models, and each tool in the MCP specification carries a name, a description and an inputSchema written as JSON Schema. For HTTP APIs, OpenAPI plays the same role, and docs sites can render reference pages from it.

Docs as code for APIs and AI agent tools

This is docs as code taken one step further. If the schema is the source and the documentation is generated from it, the docs cannot disagree with the interface. Your review process then focuses on the human-written parts: examples, guides, the why.

A practical rule: anything that can be derived from a schema should be generated, and anything that needs judgment should be written and reviewed.

Our view: write the logic once

We build NexusBloom for developers who maintain the same logic in more than one place: a web page, a CLI command, an API endpoint, an AI agent tool. Written separately, those versions drift apart, and so do their docs.

Our approach is to define a tool as one file: a JSON Schema manifest plus one pure function. From that file, NexusBloom is designed to serve the same schema and the same execution as a web page, a CLI command, an API endpoint and an agent tool. The schema is the documentation of the interface, and it is machine-readable by default.

That is docs as code applied to the interface itself. You review one file in a pull request, and every surface follows. If you are building agent integrations and are tired of tools behaving differently depending on where they run, this is the problem we set out to remove.

Benjamin

Try it on your own tools

If you maintain one piece of logic across several surfaces, NexusBloom lets you define it once and serve it everywhere. The Free plan costs €0, Creator is €9 per month and Pro is €29 per month, so you can start on a personal project and move up when a team depends on it.

Nexusbloom

Browse the NexusBloom home page to see how a manifest and a pure function become a web page, CLI command, API endpoint and agent tool. Our free JSON creator is a quick way to draft the structured data a manifest needs.

A short checklist before you commit

  • Your audience is technical and your contributors already use Git.
  • Docs live in the repository and change in the same pull request as the code.
  • CI builds the site and checks links on every pull request.
  • Anything derivable from a schema is generated, not retyped.
  • A named person owns the build, and the setup is written down.
  • You review the toolchain once a year and remove what you do not use.

FAQ

What is the difference between docs as code and documentation as code?

Nothing. Both phrases describe writing documentation with the same tools and workflows as software. You will also see "docs like code" and "docs-as-code", all meaning the same practice.

Do I need to know Git to do docs as code?

Yes, at least the basics: branch, commit, push and open a pull request. Critics point out that Git fluency can exclude non-engineers. Teams with mixed authors often add a web-based editor on top of the repository, which Sourcegraph describes as a way to mitigate the barrier.

Which file format should I use?

Markdown is the default for most teams. reStructuredText and AsciiDoc are also common, as the Home Office guidance lists. Pick the one your static site generator supports well and your team can write without friction.

Is docs as code worth it for a team of one?

Often yes, because you already use Git and the overhead is a folder and a small build. Keep it minimal, and skip ceremony such as pull requests for solo changes when the risk is low, as TechWriters.org suggests.

How do I keep API and agent tool docs in sync with the code?

Generate them from a schema instead of writing them by hand. MCP tools describe their inputs with JSON Schema, and OpenAPI does the same for HTTP APIs. Then use CI to fail the build when the generated output and the code disagree.

Sources

Created with BabyLoveGrowth's AI writer