- Initial thoughts
- 1. The power of developer tools
- 2. Live documentation
- 3. Everything-as-code applied to documentation
- 4. The AI revolution
- 5. Technical vs. non-technical contributors: choosing the right approach
- Wrapping up
- Further reading
Documentation has long been the neglected sibling of software development. For technical teams, a clear winner has emerged: Documentation-as-Code. By treating docs like source code — versioned in Git, reviewed in pull requests, built in CI/CD — developers achieve unprecedented quality, collaboration, and maintainability. But this approach isn't for everyone — and that's okay.
Initial thoughts
Picture this: A team updates their API, but the documentation lives in Confluence. Two weeks later, a developer spends hours debugging an integration issue, only to discover the docs are outdated. The fix? Someone eventually updates the wiki — until the next API change.
This scenario plays out daily across thousands of organizations. The fundamental problem? Documentation that lives outside the development workflow inevitably drifts from reality.
Documentation-as-Code (docs-as-code) solves this by bringing docs into the same workflow as code: same repository, same review process, same CI/CD pipeline. This philosophy has emerged from best practices at leading tech companies like Google, Microsoft, and GitHub. The core insight? Documentation is code — it has syntax, structure, and dependencies. Treating it any differently creates unnecessary friction.
The strength of docs-as-code builds progressively: developer tools, live documentation, everything-as-code, and ultimately the AI revolution. Let's see how.
1. The power of developer tools
Docs-as-code leverages the sophisticated tooling developers already use daily — and most of it is free and open-source, eliminating expensive CCMS licensing costs.
Git: complete traceability
Git provides capabilities that no wiki can match:
- Complete history — Every change tracked, every author identified
- Blame — Instantly find who wrote what and when
- Bisect — Track down when documentation became incorrect
- Branching — Work on updates without affecting the live version
- Reliability — Git-based tools are faster and less buggy than enterprise CCMS platforms (goodbye, random 500 errors)
Pull requests: quality through review
Teams report up to 50% reduction in documentation time compared to traditional approaches. The key? Pull requests that:
- Get reviewed by subject matter experts
- Preserve discussions alongside changes
- Ensure nothing goes live without approval
- Expose documentation to the entire team — unlike wiki edits that go unnoticed, PR-based docs get visibility from everyone watching the repository
This mirrors the benefits of code review itself — as we discussed in Every Developer Should Review Code — Not Just Seniors, review isn't just a quality gate, it's a learning accelerator. The same applies to documentation: more eyes, fewer lies.
Write once, publish everywhere
With Markdown or AsciiDoc and modern static site generators (Hugo, MkDocs, Antora, Docusaurus), the same content produces:
- Searchable websites
- PDF documentation
- API references
- Slides and presentations — Frameworks like reveal.js generate slides from the same source; IDE extensions like vscode-reveal let you present Markdown documentation instantly
You also gain full control over site appearance and features — no vendor lock-in, no waiting for feature requests. For a complete example, see our open-source asciidoc-stack — a mono-repository that generates HTML, PDF, and reveal.js presentations from the same AsciiDoc sources.
2. Live documentation
With developer tools in place, the real payoff emerges: live documentation that stays synchronized with reality. This is the natural consequence of treating docs like code.
The wiki problem: drift and duplication
Traditional wiki-based documentation suffers from two fatal flaws:
- Drift — Documentation becomes outdated because it's disconnected from the development workflow
- Duplication — The same information gets copied to multiple places, creating inconsistencies
At Google, documentation had become so bad that it was the number one developer complaint on internal surveys. Parts were obsolete, others duplicated, and there was no easy way to report errors. The fix? Same as for buggy code: moving all documentation under source control.
Same PR, same review, same deployment
With docs-as-code, documentation changes happen in the same pull request as code changes:
- API endpoint changes? Update the docs in the same PR
- New feature? Documentation is part of the "definition of done"
- Bug fix? Update the troubleshooting guide alongside the code
Outdated documentation confuses customers and increases support requests, while inaccurate internal docs slow down onboarding and increase technical debt. Under time pressure, documentation often doesn't get maintained, drifting from the updated code. Live documentation solves both problems.
CI/CD enforcement
Pipelines can enforce documentation freshness:
- Fail builds when code changes lack corresponding doc updates
- Run link checkers to catch broken references
- Validate code examples actually compile and run
- Deploy preview sites for documentation changes — as we explored in GitLab Pages per Branch: The No-Compromise Hack to Serve Preview Pages, every branch can have its own documentation preview
The result? Continuous delivery of documentation — docs that cannot drift from code because they're part of the same workflow. No more "the docs say X but the code does Y" debates.
3. Everything-as-code applied to documentation
The docs-as-code philosophy extends far beyond prose. Everything that can be expressed as code should be — diagrams, charts, timelines, even presentations.
Diagrams are a prime example. Traditional diagrams in Draw.io or simular suffer from the same drift problems as wiki documentation: binary or complex files that can't be diffed easily, separate tools requiring context switching, and versions that silently rot in a forgotten folder. With diagrams-as-code, we write text that renders automatically.
Popular diagram tools include:
- Mermaid — Native in GitHub/GitLab, flowcharts, sequence diagrams, ER diagrams, Gantt charts, mind maps
- PlantUML — UML (class, sequence, use case, activity), C4 architecture, network diagrams, wireframes, JSON/YAML visualization
- Kroki — Universal gateway to 20+ diagram engines (D2, Graphviz, BPMN, Structurizr...)
- Excalidraw — Hand-drawn style diagrams; stores as JSON that AI can read and tweak (still early days)
The key insight: diagrams become reviewable in pull requests, just like prose. And because they're text, AI can create and modify them directly.
Beyond diagrams, asciidoc-stack demonstrates many more as-code artifacts: Chart-as-code, Git-graph-as-code, Timeline-as-code, Pyramid-as-code, Word-cloud-as-code...
4. The AI revolution
The natural outcome of everything-as-code — and the one that changes everything — is AI playground. Plain text formats are the perfect substrate for AI tools, and this is where docs-as-code quietly became non-negotiable.
AI-powered writing assistance
Because Markdown and AsciiDoc are plain text, the same AI assistant you use for coding works for documentation. In your IDE, any AI coding tool with the right model can:
- Draft initial documentation from code analysis
- Improve clarity and readability
- Translate to multiple languages
- Generate examples and tutorials
- Summarize complex technical content
No context switching, no separate tools — documentation becomes part of your coding flow. Binary formats like Word or Confluence pages don't get this benefit.
The result? Documentation that would never have been written now exists. When drafting a Markdown/Asciidoc takes minutes instead of hours, teams document edge cases, add more examples, and keep content current. AI doesn't just speed up writing — it raises the bar for completeness.
AI-readable context
But the revolution goes both ways. AI doesn't just write documentation — it reads it. When documentation lives as plain text alongside code, AI coding assistants automatically use it as context to understand intent, architecture, and conventions:
- Markdown/Asciidoc files help AI suggest code consistent with the project's design
- Inline comments and Architecture Decision Records give AI the "why" behind decisions, not just the "what"
Documentation in a wiki or a PDF is invisible to your AI assistant. Documentation-as-code is part of its world. The better your docs, the smarter your AI becomes — creating a virtuous cycle where good documentation directly improves code quality.
AI integration is rapidly becoming a differentiator for documentation platforms — and docs-as-code with its plain text formats is uniquely positioned to benefit.
AI and diagram-as-code: a powerful combination
Because diagrams-as-code are plain text, AI can both read and produce them. This is a game-changer compared to binary diagram formats that remain opaque to AI tools.
AI can generate and maintain diagrams in many situations:
- Architecture visualization — Ask AI to produce a Mermaid or PlantUML diagram from a code analysis or a description of your system
- Flow documentation — AI generates sequence or activity diagrams from existing code paths or user stories
- Decision trees — Transform complex business rules into readable flowcharts
- Infrastructure mapping — Generate network or deployment diagrams from infrastructure-as-code files
- Diagram updates — When the code changes, AI can update the corresponding diagrams in the same pull request
For a concrete example, this article on GitLab Runner topologies has all its diagrams produced and maintained by AI — from architecture overviews to timelines. No manual drawing tool was involved.
5. Technical vs. non-technical contributors: choosing the right approach
Here's the honest truth that docs-as-code advocates sometimes gloss over: this approach has a real learning curve, and it's not suitable for everyone.
The barrier is real
Some critics argue that docs-as-code is a broken promise. Others add nuance — at Amazon, one team's Git workflow became so complex after a premature merge incident that a new writer admitted she was afraid to fix a simple typo.
The challenges are genuine:
- Git concepts (branches, merges, rebases) are genuinely confusing for non-developers
- Command-line tools intimidate many people
- Markdown/Asciidoc syntax, while simple, is still syntax to learn
- Pull request workflows feel foreign to those outside software development
- Complex Git workflows can paralyze even willing contributors
- Style consistency requires discipline — no CCMS to enforce it automatically
These aren't problems to dismiss — they're real barriers that affect real people. The solution? Separate technical and non-technical documentation, as we'll see below.
For technical teams: docs-as-code is the clear winner
If your documentation contributors are primarily developers, DevOps engineers, SREs, or other technical roles, docs-as-code is unambiguously the best choice:
| Advantage | Why it matters for techs |
|---|---|
| Same tools-as-code | No context switching — stay in VS Code, use Git, leverage existing skills |
| Review workflow | Code review culture extends naturally to docs |
| CI/CD integration | Docs deploy alongside code, same pipeline, same automation |
| AI assistance | Copilot and similar tools work seamlessly with plain text |
| Version control | Track changes, blame, bisect — all the tools you know |
Technical contributors already live in this ecosystem. Asking them to switch to Confluence or Google Docs for documentation creates friction and reduces quality.
For functional/business contributors: consider alternatives
When documentation involves product managers, business analysts, support teams, or other non-technical stakeholders, forcing docs-as-code can backfire.
The reality is pragmatic: these contributors have limited familiarity with developer tools, established habits with existing platforms, and often company-wide tooling constraints that aren't worth fighting. If everyone already uses Confluence, introducing Git-based workflows for a subset of documentation creates friction without clear benefit. Choose your battles — the goal is documentation that gets written, not ideological consistency.
Wrapping up
Documentation-as-Code is the definitive approach for technical teams. When developers write documentation, treating it like code — with Git, pull requests, CI/CD, and AI assistance — delivers unmatched quality and maintainability.
But we must be pragmatic: forcing Git workflows on non-technical contributors often backfires. The best documentation is the documentation that gets written and maintained. For mixed teams, hybrid approaches or user-friendly platforms with Git backends offer the best of both worlds.
Choose the right tool for your audience. For your technical docs? Docs-as-code, without hesitation.
Illustrations generated locally by Draw Things using Flux.1 [Schnell] model
Further reading
This article was enhanced with the assistance of an AI language model to ensure clarity and accuracy in the content, as English is not my native language.
Top comments (0)