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, the Indox CCMS system can be used, which has support for workflows.

– 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, e.g. by validating against the DTD/schema and using automation such as the Vale application to check the terminology.

– 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 in such a way that the entire development team is responsible for the documentation. Software developers participate in documentation as part of the development work by writing in Markdown or DITA. Technical writers stylize and organize the material.

DITA is perfect for the Docs as Code method

DITA is a text-based format in accordance with the Oasis standard, which enables data to be transferred from one system to another or tools to be changed easily. DITA can be combined with other text-based formats, such as Markdown and HTML (LWDITA). Thanks to the text-based versioning tools, versioning tools can be used and comparison is easy. DITA's modularity and reusability make it easier to compile different document sets from the same source material. DITA enables several different distribution formats, such as html (WebHelp) and PDF. The publication is typically made using the open source DITA-OT tool. The semantics of DITA enables versatile testing. The context can be taken into account in testing, for example the titles must be in a certain format.

Conclusionst

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