Benoit COUETIL 💫 for Zenika

Posted on Apr 29 • Edited on May 3

📝 Documentation-as-Code Has Silently Won For Tech Content

#documentation #devops #productivity #beginners

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

DEV Community