An Insider’s Look at Docs as Code

For the 10th anniversary of the International Conference on Technical Communication, Gaspard Bébié-Valérian, Certified Technical Communicator and Functional Consultant at Fluid Topics took the stage to explore the notion of “docOps as an in-between figure to implement docs as code”. During his talk, the audience asked several questions and we wanted to share Gaspard’s insight!

But first, let’s start with an introduction to « docs as code ».

What is docs as code?

Docs as code is the application of software development processes and tools to deliver technical documentation. It uses the same workflows and tools as development teams, including version control systems, automated tests, issue trackers, and more. It also relies on the production and management of lightweight files.

Docs as code is fairly accessible and easy to use. The necessary tools are minimalist, typically free, and as simple as text editors. Lightweight formats like Markdown or AsciiDoc are the quickest ways to start with docs as code as they both enable working with plain text files.

As with any tech paradigm, docs as code has its pros and cons.

PROS

• It fosters collaboration between tech writers and developers
• You can use the same tools as developers
• It involves developers in the production of documentation
• It reduces the overall costs of licensing and support services

CONS

• It requires a deeper technical knowledge
• It’s most appropriate for documenting software products

Many institutions and companies have turned to docs as code for their documentation processes. The British government‘s technical documentation team uses docs as code for its services and platforms. Companies like Spotify, Cloudfare, Kubernetes, Twitch, Arundo, Netflix devices, or even Bitcoin use the static site generator (SSG) Jekyll, one of the most common publishing tools for docs as code scenarios.

What are the possible interactions between docs as code and DITA?

The underlying philosophies of docs as code and DITA are different, but there are ways in which the two can co-exist.

In June of 2019, Patrick Bosek, co-founder and CEO at Heretto, presented “Living in Harmony: DITA and Markdown”. He made the following analogy:

“Markdown is like a shovel and DITA a backhoe. You have people who’ve never used the backhoe, thinking it’s too complex. And then, you have construction workers who build big buildings saying: You can’t build a big building with a shovel!.
If you start a project by yourself and don’t know how to operate a backhoe, a shovel looks like the obvious choice. There’s a place in the world for both of them, and any construction site will have shovel and a backhoe there”.

Bosek highlights the fact that each documentation standard has its strengths and we should take advantage of each one.

There are potential links between DITA and format regularly used in docs as code.

• Lightweight DITA

You can bridge the gap between structured content and continuous documentation with LwDITA, a simplified version of DITA that uses a subset of element types, attributes, steamlined content models, and a reduced set of features. Designed to incorporate HTML5 (HDITA) as well as Markdown (MDITA), LwDITA is not a replacement for DITA. It is primarily intended for organizations that integrate non-DITA literate employees into their departments. It allows authors to edit, collaborate, or publish across different organizational silos.

• DITA-Assisted Modes of Edition

The benefits of leveraging XML may make sense when supported by an interface work that focuses on an intuitive user experience. As documented automation technologies move toward end-user-friendly interfaces, developers will likely need access to specialized editing and management environments. There are solutions which facilitate the generation of consistent DITA such as Oxygen XML, IXIASOFT, Heretto, DitaToo, Componize and more.

Can metadata be added in docs as code?

Some content needs more semantics than others. In a DITA system, there are different ways to declare and add metadata, either at the topic or map level. With Markdown, there is unfortunately no semantization offered like in DITA, although it is possible to tweak existing content and add metadata. Here are some tips on how to do so:

• Use YAML files to combine metadata with a template language
• Exploit the headers of Markdown files or create a README file for each directory concerned
• Use a Markdown flavor, like Kramdown, which adds classes and IDs to inline elements
• Combine class attributes with HTML tags with Markdown content
• Leverage an SSG like AsciiDocsy which uses inline semantics. For instance: .term, .cite, .cmd, .code, .gui, .path, .case, and .tip

Is docs as code limited to the software industry?

Docs as code does apply in major companies but is often still related to software development. Heavy industries use binding specifications when producing technical documentation, like the S1000D standard for aeronautics, aerospace, naval, nuclear, railway. There are specific requirements and timelines which are not the same as in the software industry and therefore docs as code is harder to apply.

Alternatively, docs as code as a global environment may apply to different sources of content, knowledge bases, educational content, or even technologies that would rely on chatbots.

Finally, what advice would you give to a team wanting to start out with docs as code?

• Proceed step by step, start with a pilot to familiarize yourself with versioning systems and collaborative workflows
• Ramp up GIT skills for the tech writers
• Foster communication between tech doc teams and developers, engage them in the process and help them prioritize their work
• Take the time to choose and evaluate if an existing solution used for publishing, like a Static Site Generator, fits your needs
• Create a README file for the repositories to understand the scope of the project, the resources needed, the principles and guidelines
• Develop templates, implement style guides, linters and consider their integration into CI/CD pipelines
• Compare different flavors of Markdown and consider authoring with AsciiDoc or even with Lightweight DITA
• Keep abreast for articles, seminars and resources shared by the professional community: Write the docs , Tom Johnson, Anne Gentle, Brian Dominick