Apr 27, 2023
Docs as Code: A Technical Writer’s Journey
By Wen Huang, Brinqa Sr. Manager, Technical Projects
As defined by Write the Docs, documentation as code (Docs as Code) is a philosophy for creating, managing and maintaining software documentation using the same tools, processes and best practices used in software development.
This means that technical writers are integrated with the development teams. By working together, technical writers and developers have a shared sense of ownership and responsibility to ensure that the documentation is of the highest quality possible.
I first heard about Docs as Code in 2017 when a technical editor on my team told me about Anne Gentle’s new book: Docs Like Code. I had every intention of reading the book back then, but alas, life got in the way, and it remained untouched on my bookshelf.
Nonetheless, the concept of Docs as Code was crystal clear to me. Technical writers and developers share a common approach — writing documentation is akin to writing code. Just as developers rely on source control tools to manage their code, we also require similar tools to organize our files. Our updates are similar to their releases, and our defect management processes are identical. Why shouldn’t we adopt the same approach?
During that period, we were using MadCap Flare as our authoring tool. Apart from its powerful content creation and reuse capabilities, MadCap Flare also enabled us to integrate our projects with various source control providers, including Git. As our engineering team was already using Bitbucket for their source control, we requested a documentation repository to be set up and began pushing our content to it.
Initially, our writers found it challenging to adapt to the branching and merging process, but with time and practice they grew comfortable with it and appreciated its benefits. Working independently on separate documentation tasks while also collaborating became much more manageable. Although the publishing task was manual, it only required a single click to kick it off, so it wasn’t a significant inconvenience. Overall, while we didn’t refer to it as Docs as Code, it was pretty darn close.
Fast forward to 2022, when I joined Brinqa and found myself continuing the same practice, only this time in a more polished fashion! At Brinqa, we create documentation using Markdown (via a tool called Docusaurus) and store our files in Github — the epitome of Docs as Code. What’s more, as soon as a pull request gets approved and merged, our build process kicks off immediately to publish the updates to the documentation site. If that isn’t continuous integration and deployment (CI/CD) in action, I don’t know what is! Since publishing is such an easy task, we can update our documentation frequently to ensure the content is accurate.
Regrettably, I can’t take any credit for the setup; it was all done for us, ready to roll. But if you think about it, that‘s precisely what Anne Gentle outlined in her book (which I have since read): Technical writers and developers work together to create documentation using the same tools and processes used for software development. In the company she worked for, developers even took the lead in writing, starting with code comments or rough drafts on the wiki.
And that, my friend, is where my journey takes me next. I’d love to see developers drafting our documentation soon after they have written the code while the design and details are still fresh in their minds. We can then take the drafts and transform them into customer-facing documentation.
