Automate technical documentation with docs-as-code

Docs-as-code for user and developer documentation. This is how we work

• Clarify requirements. Together with you, we analyze what your target groups need and set up a suitable docs-as-code environment. Depending on your needs, we use various tools and formats such as AsciiDoc, Markdown, or DITA XML.
• Set up automatic publishing. We develop workflows (pipelines) that automatically generate HTML or PDF outputs. Upon request, we can integrate these into your existing continuous integration environment – so the documentation is almost published on its own.
• Define documentation workflows. We work with you to determine how documentation tasks are integrated into your agile development process. For example, we can use a tool like JIRA. This way, your documentation becomes agile, too.
• Define repository structures. We define how the documentation is organized in your version control system, including the folder structure and branching strategy (e.g., Git).
• Develop information architecture and templates. We design an information architecture for your documentation and create templates and terminology lists for your authors – whether they are technical writers or software developers.
• Check quality automatically. Upon request, we implement tools that automatically check whether content meets specific writing rules – for example, using the Vale linter, which evaluates texts based on defined patterns.
• Set up the right tools. We help you select and set up the right tools for authoring and publishing, such as editors like Visual Studio, IntelliJ, or Oxygen XML Editor, as well as static site generators like Antora and Jekyll.

Learn more about the docs-as-code approach in our FAQs.

FAQs – Frequently asked questions about docs-as-code

What is docs-as-code?

Docs-as-code is an approach to creating and delivering documentation for software. Docs-as-code means that you treat documentation the same way you treat source code. The docs-as-code approach combines two important aspects:

• You use the same tools for the documentation files as the developers, such as IDEs (integrated development environments), version control systems, and tools for continuous integration and delivery.
• You use the same methods as the developers, such as agile project management and Scrum.

What are the benefits of docs-as-code?

Docs-as-code offers many benefits, here are a few:

• Cost savings. By using the same tools and processes for software development and documentation, software companies can save money. There is no need to purchase a component content management system (CCMS) for software documentation.
• Versioning and collaboration. With version control systems such as Git, multiple authors can work on the documentation at the same time, tracking and editing changes as they occur.
• Workflows. Automated workflows ensure that documentation is created, tested, and published automatically.
• Author integration. When authors follow the same workflow as developers, they are fully integrated into the product development process.
• Engineers as authors: Software engineers can contribute to the documentation more easily because they don't have to change environments.

Which tools are available for docs-as-code?

• You need a text editor, such as Visual Studio Code or IntelliJ. Developer documentation is often written in a lightweight markup language such as Markdown or AsciiDoc. You can also use DITA-XML in a docs-as-code environment.
• For version control, you can use Git, for example.
• As a continuous integration tool, you can use Jenkins, Bamboo or the integrated GitLab CI to publish content stored in the version control system's repository.
• For output to HTML, you will need a static site generator. However, most static site generators only generate very basic HTML pages. For technical documentation, you need advanced features such as versioning or search integration. Only a few site generators offer these advanced features, such as Antora (AsciiDoc) and Sphinx (reStructuredText).

What is the difference between DITA and docs-as-code?

DITA and docs-as-code are two distinct yet complementary concepts in technical documentation.

DITA is an open XML standard for creating modular, reusable, and structured technical content. The goal is to create standardized, structured documentation that is easy to reuse and publish automatically. Read more about DITA XML for technical documentation.

In docs-as-code, technical documentation is treated like source code. The goal is to seamlessly integrate documentation into the software development process — making it fast, collaborative, and transparent.

Note that you can use DITA XML within a docs-as-code approach, for example, by using DITA files in Git with automated publication via CI/CD (continuous integration/continuous delivery).

Do I need to know how to code in order to use docs-as-code?

Not necessarily. Basic knowledge of Git and the supported formats (e.g., Markdown or AsciiDoc) is usually sufficient. Many tasks can be completed without programming. However, integrating with continuous integration environments often requires more technical knowledge and programming skills. More complex environments are usually maintained by DevOps specialists or technical writers with a technical focus.

In the docs-as-code approach, who writes the documentation?

It depends on the team. Often, developers write an initial draft that technical writers then revise in terms of language and structure. Docs-as-code facilitates this collaboration.

What does a typical docs-as-code workflow look like?

1. Documentation is written locally (e.g., in Markdown).
2. Changes are uploaded via Git.
3. A review is conducted via a pull request.
4. After approval, the documentation is published automatically.

Is docs-as-code a good fit for smaller teams?

Yes! Smaller and agile teams especially benefit because they can create and publish content more quickly without needing a large component content management system.