CI and CD for Documentation

CI and CD for Documentation

According to Olivier Jacques a “Documentation as Code” model isn’t just for the geeks and developers reading this, but something that can be used across all portions of an organization. Olivier, a distinguished technologist and  technology enthusiast who specializes in applying DevOps patterns across software engineering, and operations, as well as applying those practices in less technical areas, and his colleague Laurent Gil who has been shifting toward a DevOps mindset for the last 10 years, share exactly how their company, DXC Technology, has transformed an entire business with this methodology.

As they put it “we have been moving our documentation (contracts, requests for proposals, policies, technical documentation, work instructions) to a "Documentation as Code" model with a simple published goal:  improve the quality of our documentation, in the same way that our engineers have improved the quality of their software. The goal we did NOT publish is to use this move as a means to embark everyone to apply DevOps patterns such as version control everything, making work visible, CI/CD, improving feedback loops, and more.”

The Quest for Castles, Unicorns and Princesses, aka Great Documentation

Most people don’t think about documentation as a vital business imperative. Thus, it’s often the last thing people work on, and is done with little attention to detail. As Olivier explained it, at DXC Technologies documentation was sporadic with little consistency - littered with spelling mistakes, inconsistent active and passive voices and was often wrong.

Then, when the practitioners trying to use the documentation and actually understand the service would find these inaccuracies, their only remedy was trying to track down the email of the team that created it, emailing them and hoping that it got updated and put back in the right place. Add on top of this issues tactical issues with editing documentation at the same time as a team mate, and ensuring links stayed up to date and weren’t broken, and it was clear a better solution was needed. As unimportant as it may have seemed - the documentation system was hurting the overall business effectiveness.

By implementing a Documentation as Code system, DXC’s situation is drastically different. Olivier’s team is responsible for documenting 174 services which globally amounts to working with 630 contributors. Readers can now contribute to the documentation using a pull request workflow (using GitHub). Anyone can report bugs - a first for documentation - and then it can go through tests and gates and validate changes before anything is updated and merged. This has also created consistency in look, feel and voice.

What Documentation as Code Can Look Like and Why it Matters

When thinking about documenting content to ensure that the tech writers, the developers and the QA folks, were able to contribute without thinking about HTML or CSS. we needed to find something that was as close to markdown as possible. We found MkDocs which allows you to builds completely static HTML sites that you can host on GitHub pages.

DXC created a very simple structure that follows the folder structure of the Git Repository and assigns a number. They ensure that every documentation has both an in-depth table of contents but also quick “Getting Started,” examples. The full content has instant search, auto completion and exponentially easier UX than we ever had before.

As Olivier notes, DXC isn’t the only company doing documentation as code well for Microsoft, GitHub, GitLab and AWS have also transitioned to this process for 5 main reasons:

• It’s fast, secure and cheap (static sites)
• It’s easier to contribute and keep up to date
• It’s battled tested
• It’s engineered
• You can monitor with analytics

When thinking about what CICD for documentation is, as you may think you can do some of this without the process, but it’s really looking at documentation like you do code. You can really build good documentation and manage conflicts at scale. Just like developing code - when you have lots of people writing documentation and contributing to it, you need to make sure that over time, the documentation stays fresh, and doesn't break anything - just like code.

I think one voice that we can all talk and use the active voice is what you prefer, periodically checking for dead links. So that's really kind of preparing for to be able to publish continuously integrating the content and doing checks. And the CD aspect is really about automation of the publication. So how do we automate the Okay, now we have something that was approved and reviewed, how can we publish that. So all of these recipes are going to be shared by neuron, we're going to head over, we're going to share with you how to do that.

What CICD for Documentation Looks like in Practice

Most developers have their favorite IDEs like IntelliJ, Eclipse or VS Code - you can use whichever one you like. The language within the IDE, is just like any other language - as Laurel explains, its simpler than Python, but is still a language that has syntax. For example, If you talk about the traditional language like Python, you will probably want to perform some code quality just to ensure that all your developers respect the same standards, and use the same kind of formatting.

You want to make sure you have the write extensions added in so that contributors can create the appropriate information directly in the environments. This enables users to perform those pull requests and make changes and edits directly in the documentations. This makes it so you just have to review the pull request - and then the change gets published immediately.

Today, not only are DXC Technology Dev and Ops people now using GIT, Continuous Integration and Continuous Deployment for all things text, but also business consultants, marketing, legal, and our sales force. Olivier and Laurel have accumulated great outcomes. But have also made mistakes and underestimated the difficulty to do this at scale - with 30,000 active contributors. They hope you’ve learned from what they’ve implemented - and will take it back to your own company.