24. October 2023
The world of software development is constantly changing, and with it the way we document software. One innovative method that has gained popularity in recent years is Docs-as-Code or documentation as code. In this article, we will look at this exciting development and take a closer look at its application in technical documentation.
In our Meetup on the future of technical communication, we also dedicated ourselves to the topic and tested and discussed practical applications.
What is Docs-as-Code?
Docs-as-code is an approach to creating and managing software documentation in which the documentation is treated like source code. Instead of traditional documentation tools, code-based tools and versioning systems are used. This enables agile and collaborative creation, updating and management of documentation – developers and technical writers can work together on the documentation. This promotes collaboration and integration of the documentation into the entire development cycle.
The approach is primarily used in software documentation, but also offers some advantages for technical documentation.
These markup languages turn documentation into code
Instead of creating the technical documentation with a classic authoring system, a lightweight markup language can also be used to define the structure and format of the documentation. Some of the typical markup languages briefly explained:
Markdown is an easy-to-understand and widely used markup language. It enables simple formatting of text and supports the addition of links, images and lists. The syntax is minimal and intuitive, making Markdown a popular choice for many developers.
AsciiDoc is a more powerful markup language with extended functions compared to Markdown. It enables complex structures, tables and the use of macros. AsciiDoc is particularly suitable for extensive documentation with demanding requirements.
reStructuredText is a markup language that has been specially developed for Python documentation. It is easy to read and write and enables the integration of code examples. This language is often used in combination with the Sphinx tool for creating documentation projects.
YAML is often used for the configuration of Docs-as-Code workflows. YAML is a data format language that is easy to write and read. YAML is used to define metadata, configurations and structures in the documentation.
Important tools and components at a glance
The choice of a suitable markup language is crucial. These languages enable the structured markup of texts to ensure a clear presentation and consistency in the documentation. Various tools are required to ensure collaborative work between developers and editors and to generate an automated documentation process.
The main components are
Version control: A version control system such as Git is crucial for tracking changes to documentation, facilitating collaboration and managing different versions.
Text editor or IDE: A text editor or integrated development environment (IDE) allows you to write docs-as-code. Some editors offer functions such as preview and syntax highlighting to make work easier.
Build tools: Tools such as Jekyll, Hugo or Sphinx help to create the documentation website from the source code. These build tools enable the conversion of markup files into various output formats, such as HTML or PDF.
Documentation generator: A documentation generator, such as MkDocs or Docusaurus, provides a structure for organizing documentation content and facilitates the creation of a user-friendly website.
Continuous Integration (CI): The integration of Docs-as-Code into the CI/CD process enables automated builds and tests of the documentation with every change in the source code. This ensures reliable and consistent deployment.
A practical example of the use of AsciiDoc in the Docs-as-Code context is shown in a technical article on heise.de.
Collaboration platform: A collaboration platform, such as GitHub or GitLab, enables teams to work together on the documentation, provide feedback and make changes.
By implementing these elements, Docs-as-Code can be effectively integrated into the technical communication process to create agile, collaborative and well-managed documentation.
Introducing Docs-as-Code: Effort and challenges
The changeover to Docs-as-Code initially requires more work – for adapting existing documentation and the learning process. Team members need to be retrained and there may be costs for new tools and programs. Complex workflows and pipelines may be required for large projects. Docs-as-code can also simply be oversized if the information to be documented is rather simple in nature. It is therefore also important to consider potential disadvantages. In the long term, however, integrating documentation into the development process can increase efficiency and collaboration.
Advantages of Docs-as-Code for technical communication
Docs-as-code is undoubtedly an exciting development. Choosing the right tools and carefully designing workflows are crucial to the success of this method. Despite some challenges, Docs-as-Code offers a promising approach to technical communication. Here is an overview of all the advantages:
- Agile documentation: Docs-as-Code adapts seamlessly to the dynamic requirements of agile environments. The technical editorial team can react to development changes in real time, as the documentation is considered an integral part of the development process.
- Collaborative creation: Docs-as-Code promotes collaboration between developers and technical writers. The shared use of markup languages and development tools creates a bridge between the two disciplines. This collaboration leads to clear and precise documentation that is better tailored to the needs of end users.
- Automated workflows: The automation of workflows and processes is a key benefit of Docs-as-Code. By integrating CI/CD pipelines, spell checks, format checks and other quality checks can be carried out automatically before the documentation is published.
- Versioning: The integration of Docs-as-Code into version control systems enables comprehensive versioning and traceability. This is particularly important for technical writing, as changes in the documentation can be tracked and there are clear mechanisms for collaboration when creating content.
- Scalability and reusability: Docs-as-Code enables effective scalability and reusability of content. By using markup languages, certain documentation elements can be easily reused and implemented in different parts of the project. This leads to a consistent and efficient use of resources.
- Multi-channel output: Technical editorial teams are often faced with the challenge of providing content for different channels and platforms. Docs-as-Code makes it easy to adapt documentation for different output formats, be it for online platforms, printed manuals or other formats.
Overall, Docs-as-Code in technical writing offers a modern and effective method to meet the constantly changing requirements and dynamics of software development. By integrating documentation into the code development process, technical writing teams can create high-quality, up-to-date and collaborative documentation that offers added value for developers and end users alike.
Maximilian Gärber
Technical Consultant | PANTOPIX
We will be happy to inform you regularly about new articles, videos or podcast episodes.
Knowledge
Find out more about networking information
