A crash course in Docs as Code for MadCap Flare users

Technical writers have a dizzying variety of tools available to them to create and maintain documentation and other technical content.

To make sense of these different tools, we could plot them on a diagram, using criteria such as cost, complexity, implementation time, customizability, and integration with other tools and technologies. If we did this, it would be more than likely that two of the points farthest apart from each other on our diagram would be for proprietary, purpose-built software applications (sometimes referred to as help authoring tools or HATs), including MadCap Flare, and for Docs as Code.

As I noted in a previous article, the skill sets and approaches of technical writers using HATs like Flare are diverging from those of technical writers using approaches like Docs as Code. In fact, it can seem impossible to bridge the gap. But you might have to regardless, particularly if you are a Flare user looking for opportunities that require experience with Docs as Code.

This is the third in a series of articles for Flare users that provide crash courses into other popular technical writing tools. This article focuses on Docs as Code.

Defining Docs as Code

Docs as Code is not a proprietary tool like Flare or Confluence. It’s also not an industry standard like DITA. Instead, Doc as Code is an idea: As a technical writer, you should write documentation using the same tools and workflows that your organization’s software developers use to create and maintain code.

Note: There is an underlying assumption in this idea that you are creating documentation for software products and that you are working with software developers.

Each Docs as Code implementation uses a slightly different set of tools and processes. That said, most implementations include the following components:

• Version control: You maintain documentation alongside the code it documents in a version control system like Git.

• Plain text files: For easy access, you maintain documentation in plain text files and format it using Markdown or another simplified markup language.

• Static site generators: To convert plain text files to a format that is accessible to your users (in other words, a website), you use a static site generator such as Jekyll.

• Process automation: You use a continuous integration and delivery (CI/CD) pipeline to build, test, and deploy documentation in the same way software developers use CI/CD pipelines to do the same with software.

• Quality control: You use automated tools like linters to check for issues with style and grammar.

The key reason behind using Docs as Code rather than a proprietary tool like Flare is that it allows you to work more closely with your organization’s developers and use established technology to make rapid changes to your documentation’s content while still ensuring its quality and consistency.

Two different perspectives on technical writing

As you might have been able to gleam from this high-level overview of Docs as Code, Docs as Code approaches technical documentation from a different perspective from that of HATs like Flare.

Flare and similar software applications are purpose-built tools developed specifically for the needs of technical writers. They support capabilities like single sourcing and multichannel publishing that are critical for technical writers even if they are of limited value to other types of knowledge workers. For the same reason you wouldn’t expect a plumber to use a mechanic’s tools to install a bathroom fixture, so the argument for Flare and other HATs goes, you shouldn’t expect a technical writer to use the tools of a software developer, a database administrator, or even an instructional designer to create technical documentation.

Docs as Code approaches technical writing from an entirely different perspective. In a modern work environment, technical writers and software developers work side-by-side in agile teams. They support the same customers, work towards the same deadlines, and produce deliverables that are digital and delivered online. For this reason, it only makes sense for software developers and technical writers to use the same tools.

There is extensive debate on the internet (including this conversation on Reddit) about which of these approaches to technical writing is best. The fact is both approaches have their merits and both are being used in the industry, so being fluent with both Docs as Code and HATs like Flare is critical for your career development.

Bridging the gap

As a Flare user, how do you bridge the gap and learn how to create content using Docs as Code?

Write the Docs offers conferences, local meetups, a Slack community, and more for technical writers and other “documentarians.” Most of the organization’s content is geared towards writers working in Docs as Code environments. The Write the Docs website’s page on Docs as Code is a good starting point to learn about this approach. It includes links to books, recordings of Docs as Code sessions at previous Write the Docs conferences, and an open-source tool chain for Docs as Code.

You can also check out the Documentation as Code website, which offers a Hitchhikers Guide to Documentation as Code. Finally, a page in Tom Johnson’s Documenting APIs course provides a detailed introduction to Docs as Code as it pertains to API documentation.

As I noted at the beginning of this article, the gap between Flare (and other HATs) and Docs as Code is significant, but it’s not insurmountable. Both products leverage version control to varying degrees, so this might be a good entry point for Flare users into Docs as Code. Another potential entry point is Flare’s ability to import Markdown. You could import Markdown files from a Docs as Code implementation into Flare to see how the Markdown syntax translates to HTML elements like headings and bulleted and numbered lists.

Technical writers have always been translators of a sort: converting technical information provided by subject matter experts into meaningful content for our users. Now, as new tools and approaches emerge for creating that content, we need to be able to translate across these tools and approaches, regardless of how wide the divide is between them.