Implementing Docs as Code – Lessons and Benefits

Introduction

Docs as Code is a documentation methodology and practice that helps streamline the writing, editing, and publishing processes. As the name implies, Docs as Code treats all documentation as a codebase. Using some sort of version control like Git to manage the actual documents, Docs as Code prescribes writing in a plaintext markup language like Markdown, pushing that documentation through an automated pipeline that tests the quality of the writing, and ultimately building and publishing the documentation to the public. This is similar to how modern applications are published. While the setup can seem daunting, and the tools a bit foreign for a first-timer, the long-term benefits make the initial hurdles well worth the effort.

SEE ALSO: “Don’t have duplication of effort across your monitoring stack.”

How to set up docs as code

The first step in setting up Docs as Code is to select the static site generator you will use to translate your plain text markup into HTML and JavaScript. Static site generators differ from publishing platforms like WordPress, Confluence, and others, in that they do not require a database and some sort of pre-processing language, like PHP, to serve the files. This results in less infrastructure overhead, and significantly faster page loading times. Some of the more popular static site generators are:

• Jekyll, which is written in Ruby
• Hugo, which is written in Go
• Gatsby, which is written in Node.js
• Sphinx, which is written in Python, and is purpose built for documentation purposes

Typically, you should pick a static site generator based on your needs and previous programming language experience. However, most of them perform the same function, and most come with the ability to select pre-made or custom themes to change the styling of the content, similar to WordPress’ themes functionality. Note, while each of these static site generators are written in different languages, the languages really only come into play when building the site and designing and implementing a theme, meaning that for the most part writers only need to worry about the actual content.

Once you’ve picked a static site generator, the next step is determining how you want to serve your content. There’s always the option of standing up your own server using software like Apache or NGINX to serve your documentation, but the more popular option is to choose a service like GitHub or GitLab Pages, Netlify, Read the Docs, or some sort of content delivery network (CDN) like Cloudflare.

You’ll also need to select a place to host your documentation’s Git repository. GitHub and GitLab are the two most popular choices, and obviously if you’re using GitHub or GitLab Pages, you’ll want to store your repository on the corresponding website. In general, they offer similar features, though GitHub has seniority and wider adoption. Netlify, Read the Docs, and Cloudflare can all connect directly to both GitHub and GitLab.

After you’ve created a repository on one of the aforementioned Git websites, you’ll want to add some sort of testing to the repository. GitHub Actions and Gitlab CI both offer ways to implement unit tests on pull requests made to the repository. Some things you might want to test for are adherence to a style guide (Vale is the best tool in this regard), making sure there are no dead or broken links, and making sure every document has appropriate titles, social media descriptions, and slugs. Both GitHub and GitLab allow you to write your own tests, and there are many examples online that you can adapt to your needs. Note, that while testing is encouraged as early in the Docs as Code process as possible, it’s something that can be developed and refined over time, and doesn’t have to be perfect from the start. Oftentimes writers will notice patterns that later inform unit testing decisions.

With testing in place, you’re ready to finalize the CI/CD by hooking up your publishing pipeline. If you’re using one of the hosting options outlined above, then the process is relatively straightforward and can be finalized with a few clicks and a configuration file. The website will be built when a pull request is merged into a designated branch (often the main branch). If you’re hosting the file on a separate server, you might look into hooking Jenkins into your GitHub/Gitlab repository to have the site built before sending it to your production website.

Along the way there are a number of ways to preview your new and updated documentation pull requests (pull requests are how contributors signify that they’d like to add, remove, or change something in a Git repository). Netlify can be used for free in this manner, regardless of whether you’re using it to serve your actual site, as it can provide a “preview” of every pull request. This is a great way to share documentation-in-progress with development teams and other writers without the need for them to build the site locally.

Tradeoffs and considerations to make before switching to Docs as Code

Docs as Code is meant to streamline the writing, editing, and publishing process, but it’s not without tradeoffs.

Writers need to have more supporting software installed on their computers to contribute to Docs as Code documentation, and that software needs to be consistently versioned and maintained across the team. The benefit, if done correctly, is that errors are easily reproduced and corrected when they arise.

Another tradeoff is that while it is much easier for engineers and developers to collaborate on documents, non-technical users will find it much more difficult to contribute. If your Marketing or Support teams make a considerable amount of edits to your documentation, maybe Docs as Code is not right for your team.

While it’s easy to collaborate on documents through GitHub or GitLab, some coordination is needed to make sure writers know what is being worked on and by whom. This is not something only Docs as Code writers contend with, but with Docs as Code it can become easy to work on something another writer is currently working on without knowing, as the work typically takes place on a local machine. A Kanban board in Trello or some similar platform that clearly displays a given task’s assignment helps in this regard.

The last major consideration to make is that unit tests, integrations, and publishing pipelines, while normally pretty durable, still need maintenance every once in a while. So, while a team using one of the solutions mentioned here doesn’t need to contend with databases and server maintenance, they cannot divorce themselves from DevOps support without a working knowledge of all the parts in play.

Why Linode switched to Docs as Code and what we’ve learned

At Linode, we made the switch to Docs as Code a number of years ago. We started as a Wiki, switched to a few different static site generators, and ultimately landed on using Hugo. We’ve learned a few things along the way.

1.  Docs as Code can reinforce strong editorship. Nothing in our Git repository is published without a stamp of approval from an editor, and every document must pass a number of tests before it can be published. We have a staging environment with Netlify to preview the individual pull requests, and another in place for previewing a release before we publish it in GitHub. In other words, it’s difficult for a document to make it into the world with any egregious errors.
2. Docs as Code speeds collaboration across teams. We don’t need to ensure a user has log-in credentials or Google Doc permissions in order for them to preview a work in progress: they can see the actual document, styled just as it would be if we were to publish it, at every step of the way. When we have something that needs fixing, editors or collaborators can make comments directly on that line in GitHub and request the changes that need to be made, effectively blocking publication until they are triaged.
3. Docs as Code means writers can write without worrying about the presentation. Markdown is a very simple set of conventions that someone can pick up in minutes. Need a level heading? Just add a # sign. Need something in bold? Wrap it in asterisks. When the site is built, all of that gets translated into HTML more or less exactly how it was intended to be styled.
4. Docs as Code increases the abilities of writers to make contributions to open-source software and other projects. The tools learned within Docs as Code are compatible with the way the web is created, and is foundational to a larger, more proactive community engagement.

SEE ALSO: 4 Common Software Security Development Issues & How to Fix Them

Final thoughts

Docs as Code is not an overnight adoption. It requires planning and coordination. But, it can contribute a number of strengths to a writing team. Once in place, it provides formality, structure, and ease-of-mind to a writer’s process. Documents can be written and published quickly, with the knowledge that they will be tested and deployed the same way, everytime. Docs as Code isn’t for every team, but for teams with solid technical proficiencies, it can be a game-changer.

The post Implementing Docs as Code – Lessons and Benefits appeared first on JAXenter.