Docs-as-code for technical documentation

by Uta Lange , Fabian Klopfer , Frank Ralf on May 05, 2022

Corresponding services: Automate technical documentation with docs-as-code and Software documentation

Imagine you can write and update technical documentation with the same tools as the software developers use for their source code: with the same text editor and in the same IDE (integrated development environment), as plain text and versioned in your favorite version control system. Sounds impossible? It is not: It is docs-as-code.

This article is written for technical communicators and software developers who want to learn more about docs-as-code, its principles, and the benefits for technical documentation.

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 the documentation in the same way as the code. The docs-as-code approach combines two important aspects:

You use the same tooling as the developers, such as version control and continuous integration.
You use the same methods as the developers, for example agile project management.

Creating content as plain text: light-weight markup languages

One of the keys of the docs-as-code approach is that you create content as plain text in a text editor, usually in a light-weight markup language. In the following, we introduce you to the three most used ones: Markdown, AsciiDoc, and reStructuredText.

Markdown

Markdown was created as a web language to simplify the complex HTML language with its tags and elements. Markdown defines basic concepts, for example, how to write lists or create markup. Markdown is not standardized and due to its origin as an open language, there are multiple flavors, which are developed and used by different platforms and organizations. That means, companies can choose the bundles they need for their requirements.

Markdown is easy to learn and by far the most common docs-as-code language. Nearly all advanced text editors offer Markdown support. The transformation from Markdown to HTML is simple.

Advantages of Markdown:

Easy to learn
Widely used across the web
Offers a great variety of flavors

Disadvantages of Markdown:

Not standardized with the exception of some basic concepts
Extensions needed for advanced syntax features
Not explicitly developed for technical documentation

AsciiDoc

AsciiDoc is more sophisticated than Markdown and has especially been developed for technical documentation. AsciiDoc allows for complex operations to maintain documentation of nearly every size. Furthermore, AsciiDoc is standardized to a great extent. That means, everyone using AsciiDoc is using one language and does not have to decide for one flavor. AsciiDoc is maintained and further extended by the Asciidoctor consortium on GitHub.

The installation and setup processes are more complex than with Markdown. AsciiDoc allows for more sophisticated writing operations and easy publication to HTML and several other formats.

An example topic written in AsciiDoc with the IntelliJ IDE

Advantages of AsciiDoc:

Developed for technical documentation
Standardized language
Tested toolchains for publication to HTML

Disadvantages of AsciiDoc:

Not that widely used
Requires some initial installations

reStructuredText

reStructuredText (RST) is in many ways similar to Markdown. It was originally developed for documenting Python scripts. Like AsciiDoc, RST is designed for technical documentation and offers many useful methods for authors. RST is standardized and further maintained by the Docutils consortium. It can easily be extended.

Advantages of reStructuredText:

Developed for technical documentation
Standardized language

Disadvantages of reStructuredText:

Not that widely used
Requires some initial installations

Combining proven technical documentation principles

There are several proven principles for technical documentation, such as topic-based writing, reuse, terminology management, or writing rules. How do these principles align with the docs-as-code approach?

Topic-based-writing

One of the key principles in technical documentation is topic-based writing. A topic is a self-contained piece of content that has a clear beginning and ending, and serves a dedicated purpose. Possible purposes are, for example: answering one question, explaining one concept, or solving one problem. The most used topic types are concept, reference, task, and troubleshooting.

Docs-as-code works well with topic-based writing. You can create corresponding templates for the topic types in your chosen language, for example, in AsciiDoc.

Example of a concept topic created in AsciiDoc and published with Antora on a documentation website (Neptune Software)

View of the GitHub page after clicking the "Edit this Page” button in the screenshot above

Terminology and writing rules  

Because you create your content with a dedicated tool set, you can implement language and terminology checks – either in the authoring or in the build environment. This way, your texts are automatically tested against your terminology or writing rules.

Reuse 

Docs-as-code helps you reuse content. Because a topic is stored as a single entity in the version control system, you can include it anywhere in the documentation.

Some publishing tools only allow parts of a topic to be reused. With docs-as-code you can store frequently used text in a warehouse topic and integrate links to those snippets from every other topic of the documentation.

Differences to content management systems

The docs-as-code approach emulates in some ways the functions of a component content management system (CCMS). There are, however, some major differences:

Data storage: Docs-as-code requires an additional version management system, while a CCMS usually comes with an integrated way of storing data in a database.
Language and tools: Docs-as-code usually works with a lightweight markup language and is created with corresponding text editors, such as Atom, or IDEs, such as IntelliJ or Visual Studio Code. In contrast, a CCMS usually works with XML and corresponding editors, such as Oxygen.
Advanced functions: Docs-as-code mainly describes a way of writing and publishing content. More advanced functions, such as issue trackers, workflow management, review clients, or terminology management have to be handled by extra tools, requiring additional work.

An actual full-fledged component content management system does exactly that: It helps you manage your whole documentation. A CCMS provides a view of the complete documentation beyond the level of single files. A CCMS can help you with reusing content and tracking the reuse of content.

Most CCMS also provide at least basic publishing options (PDF, HTML) so you have everything you need to create and publish your documentation in one package.

Publishing in docs-as-code

You write docs-a-code in a light-weight markup language as plain text. Separating content from presentation allows you to create different output formats from the same sources, for example, XHTML, PDF, or DocBook XML.

For that you need additional tools that transform your source files into one of these output formats. Static site generators are the most common tools for creating HTML output. There is a huge number of site generators available, for example, Hugo, Jekyll, Gatsby, or Docusaurus. They use different programming languages and template engines. Most of them are available under open-source licenses.

However, most static site generators only create very basic HTML sites, mainly intended for blogs. For technical documentation, you often need advanced features like versioning or search integration. Only a few site generators provide these advanced features, for example, Antora (AsciiDoc) and Sphinx (reStructuredText).

Documentation published with Antora (Neptune)

Most of these tools are command-line tools which makes them suitable for continuous integration and delivery (CI/CD).

Continuous integration/continuous delivery

Continuous integration/continuous delivery (CI/CD) is a method where new content, code or text is constantly integrated into a publishing pipeline and deployed to production. CI/CD is used by developers and can be adapted for technical documentation.

CI/CD means that you do not have to wait several months for your content to be published on a certain release date. Instead, the documentation output is constantly generated while you are writing. This is possible because the documentation is not a standalone artifact but part of the wider development environment of your company and profits from the existing workflows.

CI/CD uses tools like Jenkins, Bamboo, or the built-in GitLab CI to publish content that is stored in the repository of the version control system.

The most common version control systems are GitLab and GitHub. After the initial integration of the documentation in the development environment has taken place, the process is highly automatized and does not require a great deal of technical knowledge from the author.

The advantage of CI/CD is that you always have a snapshot of your documentation in the output formats that you publish, e. g. HTML and PDF, independent of a release date. What is written and checked into the version control system, can be published.

Conclusion

The docs-as-code approach is best suited for developer-centric companies whose developers and technical authors are used to scripting languages, are comfortable with using version control systems, and want to directly provide or edit the documentation.

Integration of authors

Authors who write documentation as code and follow the same workflow as developers are fully integrated in the product development process.

Writing in docs-as-code usually means that authors write in a lightweight markup language, such as Markdown or AsciiDoc. Most languages are easy to learn but require advanced knowledge or tooling if the documentation gets more complex.

Yet, technical authors want and need to focus on writing. A docs-as-code approach forces them to spend some initial time setting up a documentation site and a publishing process to learn the tools and get used to the version control system. If the developers decide to change the tooling, the authors must go along.

Developers write

Developers can write a first draft of the documentation and let technical authors continue their work. This can also improve and enhance the exchange between developers and technical communicators.

Collaboration

The docs-as-code approach enables authors and developers to work together on the documentation and both feel responsible for it.

Undocumented features not released

The administration team can block features from being merged in the version control system if they are not documented. Thus, they can give developers an incentive to write documentation while features are still fresh.

Costs

By using the same tools and processes, software development companies can reduce costs and increase the number of people who create and support documentation.

Automation

The docs-as-code approach improves automation and enables companies to embed autogenerated documentation, set up automated tests, and check if the documentation is up-to-date or includes broken links.

What docs-as-code cannot offer

Besides all these advantages, it should also be stated what the docs-as-code approach cannot offer.

Firstly, there is no easy or straightforward way to incorporate knowledge graphs or ontologies into the workflow. There are different tools and workflows needed for that.

Secondly, although the reuse of topics is a strong feature of the docs-as-code approach, it cannot compete with full-fledged CCMS.

Thirdly, docs-as-code is as a method in many ways limited to writing and editing texts. It is not very well suited for the use as intelligent content or in terms of its machine processability.

A docs-as-code example: creating developer documentation

In the following example, we show you how we create, review, and publish developer documentation for a customer in docs-as-code.

We use the following tools:

AsciiDoc as light-weight markup language
IntelliJ as text editor/IDE
Git/GitHub for version control
Antora, a documentation site generator, for publishing the documentation

Authoring and review workflow

Before authors create a new topic, they create a temporary feature branch from the main branch in Git.
When authors have finished writing, they create a pull request in GitHub. In the pull request, they assign one or more reviewers.
When the review is done, the feature branch is merged back into the main branch and the temporary feature branch gets deleted.
The main branch contains the final documentation to be published.

Publishing

The publication is done via a separate GitHub repository.
Antora pulls the content directly from the Git branches.
Each push to the main branch triggers a GitHub Action Workflow to publish the documentation to a given URL.

Docs-as-code implementation by parson

We can implement a docs-as-code environment for your software documentation. Learn more.