DevOps Docs: Fast, Great Content for the Cloud
Most people think of engineering squads when you talk about DevOps. But other teams can benefit from the speed and agility that you gain from continuous delivery. So let me tell you a story about how my Doc Squad uses DevOps to build fast, great end-user content.
Abstract:
- Cloud products are driving faster publication cycles, even daily pushes.
- Automation tools and different writing techniques speed up your publication.
- You can still ensure quality when you’re writing so quickly.
Introduction to DevOps documentation
Cloud products are different; their market demands new and updated features fast. The cloud allows those features to be instantaneously available to the market. Since the competition can push features in dramatically quicker times, my own team has to be equally quick with features. Traditional development for on-premises software often included long test, translation, and fulfillment phases. Doc teams used that time in a waterfall fashion to finish and refine their work.
In DevOps, that time has evaporated. DevOps squads are pushing code daily, monthly, and weekly. Similarly, the docs for those squads need to be ready and published at the same time. Writing teams who participate in agile have leveraged sprints, multi-disciplinary teams, and MVPs to focus their work. But those agile processes are not enough.
Another unique aspect of DevOps docs is the cloud-only delivery of content. Some on-premises products still deliver physical documentation, such as printed books. But that practice has mostly disappeared. In place of physical books, those teams could still be shipping PDFs and HTML help systems along with the code on DVDs or installable images. That practice resulted in docs that became out-of-date the day that were burned onto an installable image. Quality refinements and fix pack updates resulted in complex processes to update these installed docs. Often the customers never updated their docs, even if they had the opportunity. For example, think about all those PDFs floating around in thumb drives and download folders. Finally docs, just like software code, were deeply tied to versions, such that doc teams were maintaining 8–10 versions of the same documentation sets (sometimes even more!).
What cloud docs look like is simple: HTML pages served off a website alongside the cloud product, including API docs in Swagger. The following image shows how the docs sit on the same URL as the IBM offering. You can also see how docs are accessible from the same GUI via its top menu system.
Faster publication
Now that you’ve heard how docs fit into the DevOps world. Let’s talk about how my Doc Squad delivers end-user docs, starting with speed. Our toolchain is essential to speed: both automation and its tooling.
So, we started with our own build system on Jenkins, intentionally separate from the Dev squad’s Jenkins, so that we were not impacted by their bursts, outages, and space contention. Our own build system gave us a separate staging environment that we controlled, with specialized builds for unique requirements outside of our regular offerings for prod. (Update: we now use Travis).
For source, we rely on a build system from the platform team that controls our public staging and prod deployments. The build system pulls from GitHub. Our tools and build system are a whole ‘nother series of blogs. So I’ll leave it at that for now.
All this tooling and automation lead to writing techniques that are adopted straight off the Spotify model. Our writers work in pairs, giving us higher quality (two sets of eyes) and coverage during vacations and illnesses. Those writers are actively collaborating on content with developers: doing pull requests on Dev files, like yaml, json, and python. We do iterative translation, such that we can ship files every month or sooner (instead of yearly or longer ship cycles). Those pairs ensure that quality docs can be pushed — as fast multiple times a day. Here’s a Kanban board to give you a feel of how the weekly sprints keep chaos at bay:
Again from Spotify, our Doc Squad is maniacally focused on MVP (minimally viable product) as it regards to docs. We deliver only the most essential content quickly, not content for every nook and cranny of the cloud offering. This process is also in line with industry practices of progressive disclosure and embedded content. Modern documentation sets are optimized to address the top use cases for the majority of users. In that way, we’ve stopped overwhelming users with “nice to know” info. Instead, we deliver what they “need to know” to achieve those business goals.
Quality when you have little time
Quality assurance might sound daunting when we’re working so fast. Yet, our tools have reduced manual (and thus error-prone) activities. We’ve improved our quality with grammar, punctuation, and style errors with linters and Acrolinx. Accessibility testing is done iteratively as we deliver smaller chunks of content, headed by an accessibility focal. More automaton tools can flag build problems, hyperlink issues, and bad file references. For example, a Slackbot provides a daily snapshot of doc tests:
But tools are not the whole answer. As mentioned previously, knowledge sharing and expertise occur through paired writers. Those pairs are responsible for peer reviews, translation, diagrams, and so forth. Our squad is spread across Austin, Raleigh, Rochester, and Hursley. And, we collaborate with engineers across the United States, Ireland, England, Germany, Israel, India, and China. Thus, we rely on Slack, GitHub, Mural.ly, video conferencing, and other collaboration tools. To ensure collaboration, team building is a priority. So Slack is a great place to have silly conversations alongside technical discussions (hello giphy). Our squad plays games online, regularly. We’ve even appointed an Ambassador of Fun, further cementing team cohesion.
Low-cost user testing is another way that we validate and improve the docs. Our strategy is to test early and with low-fi tools. We partner with our Design counterparts as they do user testing. When it’s time-inefficient to find a customer to test with, we tap developers in the office who have similar experience. Paper prototypes, sketches, and design walkthroughs are just a few of the methods we use to see how well the content works for users.
Continuous integration, continuous improvement
Our future is true to DevOps: continuous improvement in an incremental fashion. We will have even more automation with our toolchain. For example, we’ve already developed build files to make translation shipments easier. We also expect to automate more of our translation file handling. Another possibility is for us to leverage our build environment to run even more automation, such as pre-flight translation tests.
Doc squads can adapt and thrive in a DevOps world: writing fast, writing well, and showcasing business value. In the end, your company can see content that drives revenue, lowers costs, and even engages customers.
