Glossary
Docs as code
Definition
Docs as code is the practice of writing documentation in plain-text markup, storing it in version control alongside the source, and publishing it through an automated build — applying the same tooling and review process to docs that engineering teams already use for software.
How the workflow works
Docs as code is less a tool than a set of four commitments, borrowed wholesale from software practice:
- Plain-text source. Markdown, MDX, AsciiDoc, or reStructuredText — formats that diff cleanly, rather than a proprietary binary or a database-backed WYSIWYG.
- Version control. Docs live in Git, often in the same repository as the code they describe. History, blame, and branching come free.
- Review through pull requests. A documentation change is proposed, reviewed, and merged the same way a code change is — by the same people, in the same place, with the same conventions.
- Automated publishing. A merge to the main branch triggers a build that renders the source into a static site and deploys it. No one presses publish.
Where it came from
The term was popularised in the mid-2010s as static site generators matured and engineering teams noticed that their documentation workflow was the only part of their process still running on email attachments and a CMS login. The appeal was immediate and mostly cultural: putting docs in the repository puts them in front of engineers, and a documentation change that arrives as a pull request is one an engineer will actually review.
What it solves
- Review gets real. Documentation changes are visible next to the code changes they accompany, which is the only moment a reviewer has the context to catch an inaccuracy.
- History is legible. You can see when a page changed, who changed it, and which commit it shipped with.
- Publishing stops being a task. Removing a manual step removes a place for work to queue up.
- Docs can be tested. Link checkers, linters, and spell-checkers run in CI like any other gate.
Where it stops short
Docs as code fixes the pipeline. It does not, on its own, fix the drift.
A Markdown file in the same repository as the function it describes is still a separate artifact, written by hand, that a developer has to remember to update. The commit history will faithfully record that the page hasn't been touched in eleven months; it will not update it. Teams that adopt docs as code and then find their documentation is still stale usually haven't done anything wrong — they've adopted a workflow improvement and expected a synchronisation guarantee.
The practical limit is worth stating plainly: docs as code makes documentation reviewable, and review only catches what a reviewer happens to notice.
Docs as code vs. generated documentation
Generated documentation goes one step further by removing the hand-written artifact for anything derivable from the source. Signatures, parameters, endpoints, and configuration options are read from the code rather than described in a parallel file, so they cannot fall out of step with it.
The two are complements rather than alternatives. Conceptual explanation, architectural narrative, and anything requiring judgement about what a reader needs to understand benefits from being hand-written and reviewed. Reference material generally does not.
Git2Docs sits on the generated side: it reads the repository, synthesises the documentation, and resyncs on every push, while leaving section-level editing available for the places a human voice matters.