Docs-as-Code: Break free from documentation silos¶
Wondering if the Docs-as-Code approach is suitable for your team?
Docs-as-Code treats documentation the same way software teams treat source code. Content lives in plain text files, typically Markdown, in the same version control system as the product it describes.
A static site generator builds it into a website, and the same continuous integration system that builds and tests the product also builds and publishes the docs. Every change goes through a pull request, gets reviewed, and gets merged, exactly like a code change.
Here's how it responds to the pain points teams run into without it:
Tooling¶
| Pain point | Docs-as-Code response |
|---|---|
| Proprietary tooling is too expensive to open up to more people in the organization. | Open-Source tooling costs nothing extra to add another contributor. |
| Our tools can't handle our projects' complexity. | Plugins extend the toolchain to handle your project's complexity. |
| A single vendor controls a roadmap that no longer fits us. | No single vendor sets the roadmap, because you can submit changes yourself or fork the project if priorities diverge. |
| Several documentation systems need consolidating into one that will last. | One open format replaces several legacy systems for good. |
| Our tooling can't be self-hosted, so regulated content has nowhere to go. | Self-hosting keeps regulated content behind your firewall. |
| Search doesn't work, so answers that already exist stay hidden. | Built-in search finds answers that already exist. |
Workflow¶
| Pain point | Docs-as-Code response |
|---|---|
| Documentation can't keep pace with product development. | The same system that builds and tests the product also builds and publishes the docs, so releases stay in step. |
| Internal and external documentation live in different systems and drift apart. | One plain-text source feeds both internal and external documentation, so they stop drifting apart. |
| Changes go live with no preview, so mistakes surface after publication. | Pull request review catches mistakes before anything goes live. |
| Keeping multiple product versions in sync is manual and error-prone. | Branching per release keeps multiple product versions in sync automatically. |
Collaboration¶
| Pain point | Docs-as-Code response |
|---|---|
| Specialized tooling makes onboarding new contributors slow. | Contributors use the git workflow and the editor they already know, so onboarding needs no extra training. |
| Engineering, product, and documentation work in silos. | The same version control system and review process bring engineering, product, and documentation together. |
| Subject matter experts avoid the documentation tool, so writers translate for them. | Subject matter experts write directly instead of routing changes through a writer. |
| Documentation changes skip review because they aren't part of the code review process. | Documentation changes go through the same pull-request review as code, so they don't get skipped. |