Docs as Code – A Technical Writing Approach From The Software Industry

Docs as code as a technical writing approach

Docs as code is a method for creating software documentation with largely the same tools that are used in software development. Git-based file management, extensive automation, a collaborative review process, and “lightweight” markup languages all belong to this process. This means pure text files are labeled with structural information and layout instructions. Two of the most widely known markup languages are HTML and XML. The content of these files is structured using a range of instructions in angle brackets, which are called ‘tags’. There are no tags in the markup languages for docs as code (e.g., AsciiDoc, reStructured Text, or Markdown); instead, the content is marked up using special characters.

Docs as code in action

When docs as code is used, technical writing is integrated into the software development toolchain. Content is usually created in editors like Visual Studio Code, IntelliJ IDEA, or Markdown Pad, although any text editor can be used in principle. Technical writers use repositories for content management with a docs as code toolchain. The source files are either maintained together with the software code in one repository or kept separate from the software code in a dedicated repository for the documentation. GitHub, Bitbucket, and GitLab are popular platforms for Git-based management of content in repositories. The content of the source files can then be prepared for the end user in HTML or PDF format using tools such as Antora, Sphinx, Hugo, or Jekyll.

The key elements of a docs as code toolchain can be combined with one another in a flexible manner. The tools chosen depend on which software development environment is being used and how it is best to organize collaboration in the team. Often scripts are used later—for example, to automate processes—in addition to the tools initially selected.

Docs as code: opportunities and risks

Technical writers who are used to working with a CCMS are likely to find docs as code a little alien at first. However, this method does offer some advantages, the most important being that the software development and technical documentation processes can run in parallel, as both make use of the same tools. Contrary to CCMS data, docs as code documents can be used by anyone with access permissions; access to a special system is not required. Unlike the markup language in XML files, the languages used by docs as code can be read comparatively fluently, which is advantageous if you want users to have a quick overview of the content.

For technical writers, these advantages often mean moving away from concepts and ways of working that modern technical documentation has come to value. While reusing content or integrating image and graphics editing is possible, it's perhaps not quite as easy as in some CCMS. When it comes to metadata management in particular—for example, forwarding content to content delivery portals later or working with ontologies—there are not yet any sophisticated solutions.  Integrating product data from other systems, such as PIM systems, is also uncommon.

The strengths of the docs as code method really come to the fore when technical writing needs to be seamlessly integrated into the software development process. This is particularly helpful when the developers also contribute content to the documentation. By using the same tools, implementing the established four-eyes principle through efficient, convenient review processes, and automating different steps in the document preparation process, the documentation can be continuously updated and published in as few cycles as the software. For these reasons, docs as code is becoming a more popular method for technical documentation among developers. Nevertheless, technical writers should analyze precisely whether the advantages of a closer relationship with the development team justifies the restrictions this brings to their work.