Documentation as Code: Shifting Value#
In relation to software, code means several things. A technically accurate definition of code is that it is a set of instructions that a computer executes. A practical definition views code as a collection of files that contain the logic of what the program does.
This definition is practical because this is the perspective where you reason about code.
The popular concept Documentation as Code is actually based on a simplified treatment of code: stored under a version control system, updated through PRs, and pushed through the pipeline that builds the application. Documentation as Code borrows version control, update model, and automation on the grounds that both kinds of source code are plain files that a repository can hold.
However, sharing a toolchain is not the same as treating documentation as code.
Besides, the tools were never specific to application code in the first place.
I Will Show You the Source: What Do You See?#
Application source code and documentation sources are not the same kind of thing. An application becomes a product only after a series of transformations. Its source is inert: it must be built and run before it delivers any practical value. Until then its capabilities are unknown.
Documentation is already a product in its source form, because reading it is enough. Both the structure and content always deliver valuable information.
This is why the readability of the source is among the most essential requirements of every plain text documentation format. In fact, documentation is even more beneficial in source code form. Source files in Asciidoc, or reStructuredText, or Org-mode carry information about crucial elements that the rendered output discards.
In Documentation as Code, the value of documentation as a product is not considered.
Important
Why does it even matter? Acknowledging that documentation is a product does not deny the fact that it is the rendered form that matters most. Thus, both pipelines are aligned perfectly: sources updated, sources reviewed, product built and deployed.
It matters because it shifts the focus from a shallow procedure to a profound and important process while staying in the same context.
Use a Pipeline: They Are All the Same.#
The end products constructed by the build pipelines have different fates in documentation sources and application source code.
For documentation, the story ends there. The end product is made available to readers. For application, the built program goes to testing and it takes a number of iterations until the result is good enough for a public release.
Thus, Documentation as Code applies to the build pipeline only: from the point when an updated documentation source is pushed to the version control system up to the point when the build process outputs a documentation site or a PDF document. The stages of this process are quite similar to the build pipelines of application code.
On stage 1, the developer updates the application source code and the author updates the content and structure of documentation sources.
On stage 2, the developer submits the application source code for review and the author requests a review from the Subject Matter Expert.
On stage 3, the changes are merged to trigger the build process. (runs automatically; nothing interesting happens after it has been set up.)
Stage 3: Building the Output#
Stage 3 is very important for those DevOps engineers who set up the pipeline. Thanks to Documentation as Code, they can apply the same approach to both documentation sources and application source code.
For documentation, nothing interesting happens on this stage. Ever. Even in the case of a single source environment that produces multiple variants of documentation for different groups of readers — internal+external documentation, multiple customers, multiple output formats, or a combination of these — this stage hardly changes a lot.
This stage can be simplified to building output locally. In this case calling the building a stage is too much.
Important
If this stage is not boring, then the documentation is built on top of an inapt framework.
Stage 2: Reviewing the Changes#
This stage introduces an important distinction between processing application source code and documentation sources. For both, this stage is the review. In case of application source code, the review is done by an experienced colleague familiar with the code base and rules of updating it properly.
To review documentation sources, it may require attention of another documentation author. But this stage only works if the Subject Matter Expert is involved. And the Subject Matter Expert is not the same role as the reviewer of application source code. The Subject Matter Expert is knowledgeable of the subject being documented and is the owner of the resources which were provided to be used as the basis of the update. But the Subject Matter Expert need not know the complexity of documentation sources.
One of the declared values of Documentation as Code is that reviewers may update documentation, too. For a small project, it might work. For complex projects, the Subject Matter Expert can make consistent and correct changes to documentation sources only if this person understands the structure, guidelines, layout principles, and the authoring environment as well as assumes the author’s responsibility. In other words, the Subject Matter Expert must become an author, too.
This is where Documentation as Code becomes uncomfortable as it places no such demands.
Stage 1: code|doc#
With the build pipeline being boring on stage 3 and the review process not correctly shaped, you can observe a paradox. Documentation as Code is not directly related to code but the case where code contributes to documentation is not related to Documentation as Code.
Documentation as Code declaring resemblance to code (as one might conclude from the very name) only takes a toolchain that happens to be used in software development. However, the toolchain is not directly related to code. On the other hand, the real contribution of code to documentation goes completely ignored.
In software, code is broader than source code. It covers a program’s behaviour, its algorithms, and its structure — not the symbols in files processed by the toolchain. Documentation as a product is the content: the information and the means of organizing it for readers. The logic and structure which are used to reason about what software does — that’s what makes application code a product, too.
It is reasonable to suggest that, as products, documentation and application code are comparable. This comparison has exactly one beneficiary: the author.
code|doc: Effective Immeditely#
A practice proven for application code carries a value that documentation may be missing. It is not application code being useful by introducing C++ structures in prose. It is viewing parts of documentation based on principles that make those practices valuable. Just a few examples:
Variables
In application code, a variable must be defined before it is used. In documentation, terms are the variables. They must be declared properly.
Modules
In application code, modules group what belongs together and separates what does not. Documentation is broken down into sections; what modularity adds is the criterion: a section must hold a selection of related ideas and nothing more.
Don’t Repeat Yourself
In application code, a piece of logic is defined in one place and called wherever it is needed. In documentation, the DRY principle requires the same. In practice, this criterion guards against saying the same thing in multiple places — just using a different wording.
None of these will arrive unchanged. A variable becomes a defined term, a module becomes a bounded section, Don’t Repeat Yourself becomes one concept defined in exactly one place along with related details. Best practices change form because documentation brings the same discipline into a different context.
Reasoning from Another Context: Is What You Get#
Discipline that the two products share is the precision of writing. Application code reaches precision through incorporating the reasoning into the context of operation. Documentation reaches it through incorporating the reasoning into its content and form. A practice proven for one can be expected to have an equivalent in the other. And the toolchain has nothing to do with it.
- version:
1.0
- revision:
2026-09-15
- written.by:
Borys Belinsky (borys.belinsky@protonmail.com)
- assisted.by:
Anthropic Claude, Sonnet (Effort: High)