How to Integrate DITA with Docs as Code: A Guide to Agile Technical Documentation

What is Docs as Code?

A typical problem with documentation is that it lags behind product versions or does not correspond to different versions of a modular product. With a modular approach, the documentation can be targeted to match the product configuration. The goal of the method is to combine the development of the product and its documentation. This is achieved by applying the same proven tools and methods to documentation as to software development. These tools and methods vary from organization to organization. The starting points of Docs as Code are:

– The document is in a standard text format, such as DITA, HTML or Markdown. These can be modified with text editors developed for them, for example Oxygen XML Editor.

– A service management system (e.g. Jira) for change management, which is also typically used in software development. The purpose is to ensure that product changes are also reflected in the documentation.

Version control (Git), in the Docs as Code method, documentation typically follows the versions of the product being documented. Alternatively, Indox can be used, which has workflow support.

– Automatic compilation and distribution of documentation. If there are changes to the documentation, it triggers compilation, which creates documentation suitable for the new version. This corresponds to the CI/CD thinking of software development, i.e. continuous integration and continuous delivery. Thanks to the modularity of the documentation, it is possible to target the documentation to match the customer's product configuration.

Documentation testing can be automated by, for example, validating against DTD/schema and using automation for terminology checks, such as the Vale application.

– Documentation is combined with the development method used. For example, the Scrum of software development, where documentation is done as part of sprints.

The Docs as Code method can be implemented so that the entire development team is responsible for documentation. Software developers participate in documentation as part of their development work by writing in Markdown or DITA. Technical writers style and organize the material.

DITA is perfect for the Docs as Code method

DITA is a text-based format compliant with the Oasis standard, which enables seamless transfer of content between systems or effortless switching of tools. Other text-based formats, such as Markdown and HTML (LWDITA), can be combined with DITA. Thanks to its text-based nature, versioning tools can be used, and comparisons are easy. DITA's modularity and reusability facilitate the creation of various documentation sets from the same source material. DITA enables multiple distribution formats, such as HTML (WebHelp) and PDF. Publishing is typically done using the open-source DITA-OT tool. DITA's semantics allow for diverse testing. Context can be considered in testing, for example, titles must be in a specific format.

Conclusions

DITA fits well with the Docs as Code method. Complex documentation can be done with DITA, but for easier documentation it can be kept simple. DITA enables the controlled development of documentation as the product becomes more complex over the years. Index IT helps your organization move to the Docs as Code method.

Sources:

https://istc.org.uk/wp-content/uploads/2021/11/George-Bina-%E2%80%93-Docs-as-Code-and-DITA.pdf