One source of truth
Docs sit next to the code in the same repository. They branch, merge, and version with it — no more wikis drifting out of date.
the hitchhiker’s guide to documentation as code
Treat your docs as code.
Plain-text source. Version control. Peer review. An automated build. The same discipline you trust for software, applied to the documentation around it.
12== Quality Goals
13
14Performance is important.
14Render the report in under 2s (p95).
15
16// reviewed in PR #42, built by CI
01 — why it matters
01
02
03
Documentation that lives where the work happens.
Reviewed, not guessed
Changes go through pull requests. Every edit is diffable, discussable, and traceable to a reason and an author.
Built automatically
CI turns plain text into polished HTML, PDF, or a wiki — on every commit. Publishing stops being a manual chore.
02 — the idea
It’s a practice, not a product.
Docs-as-Code is a way of working: lightweight markup, a version-control system, reviews, and a build pipeline. The tools are interchangeable — the principles are what matter.
- Plain-text markup — AsciiDoc or Markdown
- Diagrams as text — PlantUML, Mermaid
- Version control — Git
- Review — pull requests
- Automated build — CI/CD
- Proven structure — arc42, C4
03 — the workflow
Four steps, end to end.
Write, version, build, publish — the same loop your code already follows.
write
Author in plain text
Open your editor. Write AsciiDoc or Markdown. Sketch diagrams as text right beside the prose.
version
Commit to Git
Every change is tracked, attributable, and revertible. Branch for big edits, review before merge.
build
Render on CI
A pipeline transforms the source into HTML, PDF, or Confluence pages — automatically.
publish
Ship it
The output deploys like any other artifact. The latest docs are always one commit away.
04 — make it real
A practice needs a toolchain.
docToolchain wires the whole loop together — AsciiDoc, PlantUML, arc42 templates, and exports to HTML, PDF, and Confluence. Open source, batteries included.