Docs-as-code
What Is Docs-as-code?
Section titled “What Is Docs-as-code?”Docs-as-code is a documentation approach where technical writers and developers work in the same environment and use the same tools. By storing documentation in version control and writing in lightweight formats such as Markdown, teams gain a faster review process, clearer collaboration, and a workflow that aligns with modern software development.
Benefits
Section titled “Benefits”Using a docs-as-code workflow with Markdown, compared to traditional DITA-based systems, provides several advantages:
- Faster and more structured reviews through pull requests and inline comments.
- Flexible content layout without rigid XML schemas.
- Easy integration of add-ons that transform documentation into a product.
Add-ons To Integrate
Section titled “Add-ons To Integrate”The following tools extend and enhance a docs-as-code environment:
- Litlyx
- A lightweight, GDPR-compliant analytics tool that provides traffic insights for documentation portals. See Litlyx webpage for more information.
- Swagger
- An interactive API documentation tool that displays example requests, response schemas, and live testing. See Swagger webpage for more information.
- GitLens
- A Git visualization extension for VS Code that helps contributors understand commit history, branching, and collaboration patterns. See GitLens wepage for more information.
Docs-as-code VS DITA
Section titled “Docs-as-code VS DITA”Docs-as-code is often preferred over DITA in the following situations:
- Software documentation, where writers benefit from using the same tools as developers.
- Cost efficiency, avoiding licensing fees associated with DITA-based systems.
- Flexibility, allowing writers to structure content without strict XML constraints.
- Integration, enabling documentation to fit naturally into the IT ecosystem and CI/CD pipelines.
Further reading
Section titled “Further reading”- Read Docs-as-code from Write The Docs for more information.