In many organisations documentation lives in one place and the work in another: procedures in a shared document nobody updates, instructions in a rarely visited wiki, the crucial notes in emails. The result is familiar to everyone: outdated documentation that people barely trust.
The approach called docs as code proposes treating documentation with the same tools and habits as code: plain text files, version control, review before publishing, automated checks. You do not need to be a programmer to adopt it, but you do have to accept working with text files instead of a visual editor.
The elements
- Plain text files, usually Markdown, sometimes reStructuredText or AsciiDoc.
- Git to keep the history of every change, know who changed what and roll back.
- Review through change requests (pull requests or merge requests): no page changes without another person having read it.
- A static site generator that turns the files into a navigable site with menus, search and a table of contents.
- Automated checks that verify links, spelling and style on every change.
Why it works
The main advantage is that documentation is updated at the same moment as the thing it documents changes. If a backup procedure changes, the configuration change and the documentation change go into the same request and are reviewed together. A reviewer can reject a technical change that does not update the instructions.
Other concrete advantages:
- Git history answers questions such as «since when has the procedure said this?»;
- texts can be searched and edited in bulk with ordinary tools;
- no dependency on a platform: the files stay readable even without the site.
A typical structure
project/
├── docs/
│ ├── index.md
│ ├── installation.md
│ ├── guides/
│ │ ├── first-login.md
│ │ └── daily-backup.md
│ ├── reference/
│ │ └── configuration.md
│ └── img/
└── mkdocs.yml
A widely used organisation divides content by purpose: tutorials for beginners, how-to guides for specific tasks, reference for the full list of options and parameters, explanations for the reasons behind choices. Keeping these four types separate avoids pages that try to do everything and do nothing well.
Choosing the generator
| Tool | Format | Strengths | Suited to |
|---|---|---|---|
| MkDocs (with the Material theme) | Markdown | Simple configuration, built-in search, polished look | Manuals, procedures, internal documentation |
| Sphinx | reStructuredText, Markdown via the MyST extension | Powerful cross-references, PDF output too, automatic Python code documentation | Large software projects |
| Docusaurus | Markdown, MDX | Multiple versions, built-in blog | Product documentation |
| Hugo | Markdown | Speed, great flexibility | Sites mixing documentation and content |
To start, MkDocs is the lowest-friction choice: one configuration file, a folder of Markdown files and two commands.
pip install mkdocs-material
mkdocs serve # local preview that refreshes on every save
mkdocs build # generates the static site in the site/ folder
Automated checks
The strength of the method shows when you add checks that run by themselves on every change:
- Broken links: dedicated tools check that every internal and external link works.
- Markdown formatting: markdownlint flags skipped headings, inconsistent lists, stray spaces.
- Style and terminology: Vale applies writing rules defined by the team, for example «write email, not e-mail» or «avoid simply».
- Spelling: command-line spell checkers with a dictionary of the project's technical terms.
- Build: if the site does not build, the change is not accepted.
These checks run in the continuous integration systems of Git platforms and report errors directly in the change request.
The real difficulties
Docs as code is not suitable for everything. Non-technical people may find Git awkward; for them it is best to offer the platform's web editor, which lets them edit a file and open a request without installing anything. Heavily designed documents, such as brochures or contracts, are still better in a word processor.
In my work I use it for everything that describes systems and procedures: configurations, operational guides, runbooks for interventions. That is where up-to-date documentation really makes the difference.
In short
- Docs as code means documentation in text files, managed with Git and reviewed before publishing.
- Documentation changes in the same request as the thing it documents, and stays current.
- Splitting content into tutorials, guides, reference and explanations makes pages more useful.
- MkDocs is the simplest starting point; Sphinx suits large software projects.
- Automated checks on links, formatting and style maintain quality effortlessly.
