Docs as Code Implementation – Lessons and Benefits



Docs as Code is a documentation methodology and practice that helps streamline the writing, editing, and publishing processes. As the name suggests, Docs as Code treats all documentation like a code base. Using a kind of version control like Git to handle actual documents, Docs as Code prescribes writing in a plain text markup language like Markdown, pushing that documentation through an automated pipeline that tests the quality of it. writing, and ultimately by building and publishing documentation to the public. This is similar to how modern apps are published. While the setup may seem daunting and the tools are a bit foreign to a beginner, the long term benefits make the initial hurdles worth it.

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

How to set up documents as code

The first step in setting up Docs as Code is to select the static site builder that you will use to translate your markup from plain text to HTML and JavaScript. Static site builders differ from publishing platforms like WordPress, Confluence, and others, in that they don’t require a database and some sort of pre-processing language, like PHP, to serve files. This translates to less infrastructure overhead and significantly faster page load 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 specially designed for documentation purposes

Generally, you should choose a static site generator based on your needs and previous programming language experience. However, most of them perform the same function and most offer the option to select predefined or custom themes to change the style of the content, similar to the functionality of WordPress themes. Note that while each of these static site builders is written in different languages, the languages ​​really only come into play when building the site and designing and implementing a theme, which means that for the most part editors only have to worry about the actual content.

Once you’ve chosen a static site builder, the next step is to determine how you want to deliver your content. There is always the option of setting up your own server using software like Apache or NGINX to serve your documentation, but the most 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 will also need to select a location to host the Git repository for your documentation. 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 functionality, although GitHub is older and more widely adopted. Netlify, Read the Docs, and Cloudflare can all connect directly to GitHub and GitLab.

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

Once the tests are in place, you are ready to finalize the CI / CD by connecting your release pipeline. If you are using any of the hosting options described above, the process is relatively straightforward and can be completed 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 are hosting the file on a separate server, you might consider hooking Jenkins to your GitHub / Gitlab repository to have the site built before uploading 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 they want to add, remove, or change something. in a Git repository). Netlify can be used for free in this way whether or not you use it to serve your actual site, as it can provide a “snapshot” of every pull request. It’s a great way to share current documentation with development teams and other writers without them needing to build the site locally.

Tradeoffs and Considerations Before Switching to Docs as Code

Docs as Code aims to streamline the writing, editing, and publishing process, but it’s not without compromise.

Editors should have more supporting software installed on their computers to contribute to Docs as Code documentation, and this software should be versioned and maintained consistently across the team. The advantage, if done correctly, is that errors are easily reproduced and corrected when they occur.

Another tradeoff is that while it’s much easier for engineers and developers to collaborate on documents, non-technical users will have a much harder time contributing. If your marketing or support teams are making a significant amount of changes to your documentation, maybe Docs as Code isn’t 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 they’re working on and by whom. It’s not something that only Docs as code writers grapple with, but with Docs as Code it can become easy to work on something that another writer is currently working on unknowingly because the work usually takes place. on a local machine. A Kanban board in Trello or a similar platform that clearly displays the assignment of a given task helps in this regard.

The last major consideration to consider is that unit tests, integrations, and release pipelines, while normally quite durable, still require maintenance from time to time. So while a team using any of the solutions mentioned here doesn’t have to deal with databases and server maintenance, they can’t part with DevOps support without a working knowledge of all of the tools. parts in play.

Why Linode switched to Docs as Code and what we learned

At Linode, we switched to Docs as Code several years ago. We started as a Wiki, moved on to a few different static site generators, and ended up using Hugo. We have learned a few things along the way.

  1. Docs as Code can reinforce strong writing. Nothing in our Git repository is released without a publisher’s seal of approval, and each document must pass a certain number of tests before it can be published. We have a preview environment with Netlify to preview individual pull requests, and another in place to preview a version before we publish it to GitHub. In other words, it is difficult for a document to reach the world with glaring errors.
  2. Docs as Code speeds up collaboration between teams. We don’t need to make sure that a user has Google Doc credentials or permissions in order for them to preview a work in progress – they can see the actual document, as it would be. if we publish it, address every step of the way. When we have something to fix, editors or contributors can comment directly on that line in GitHub and request any changes that need to be made, thus stopping the post until they are sorted.
  3. Docs as Code means copywriters can write without worrying about presentation. Markdown is a very simple set of conventions that someone can figure out in a matter of minutes. Need a level title? Just add a # sign. Need something bold? Wrap it in asterisks. When the site is built, it is all translated into HTML more or less exactly as it was meant to be styled.
  4. Docs as Code increases the ability of authors to make contributions to open source software and other projects. The tools learned in Docs as Code are compatible with how the web is created and are essential to broader and more proactive community engagement.

SEE ALSO: 4 Common Software Security Development Problems And How To Fix Them

Final thoughts

Docs as Code is not an overnight adoption. It takes planning and coordination. But, it can add 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, knowing that they will be tested and deployed the same way, every time. Docs as Code isn’t for every team, but for teams with strong technical skills, it can be a game-changer.

Source link


Leave A Reply