In my last article about content strategy, we walked through the philosophical change that's happening around technical documentation, and discussed new and exciting ways to care about our users.
Now that we have all this great insight about who, what, when, where, and why we write documentation, let's look at how we can practice what we preach and deliver all this wonderfully useful content to our eager readers. For me, this means DevOps for Docs.
That's right, DevOps. The term that launched a thousand flamewars. Personally, I'm allergic to flamewars, and if my work as a scrum master (retired) taught me anything, it's that how you implement DevOps is really up to you: Take what you need, don't worry about what you don't, as long as your heart is in the right place!
Your personal DevOps manifesto
Thanks to the, umm... flexible definition of DevOps, there are plenty of ways to break down and group these practices. Luckily, the docsphere can afford a more simplified breakdown, as our main output is prose and not code.
Once again, I've taken a look at what the open source communities and the Red Hat documentation teams are doing in this realm, and will now attempt to break down DevOps for Docs into the following categories:
- Unified toolchain
- Continuous delivery
- Collaboration
Some of the practices and tools that I'm about to list have been around for years, others are just starting to gain traction around the docsphere. What's exciting to me is that writers can leverage all this existing knowledge, skills, and tools from our engineering counterparts to create speedy and smooth content delivery for our eager users.
It also means that we can do some pretty cool stuff with our content!
Unified toolchain
From source control, markup languages, and publication parsers, to continuous integration and automated testing, long gone are the days of the simple word-processor-to-printed-book. Remember documentation CDs? It wasn't pretty.
Open source technologies have played a critical role in driving this effort, as the need for quick, streamlined, and integrated docmentation created an entire family of content authoring and publication tools that play quite nicely with the code that we document.
At the core of most documentation nowadays you can find source files, written in one or more of the host of markup languages that we have at our disposal, such as DocBook XML, Markdown (all 31 flavors of it), AsciiDoc, and reStructuredText. These tagged text files are usually source-controlled with Git (with or without the help of GitHub or GitLab), the same source control platform that most open source communities as well as Red Hat use for their code.
Many open source projects manage their documentation near or with their code, and some employ interesting tricks to align the publication flow with the project build and to simplify content contributions. For example, KDE uses some cunning scripts to convert Wiki libraries to DocBook-based guides, so you can author in simple Markdown and still enjoy the robust publication capabilities of DocBook. NixOS uses the Nix package manager to package the Nix documentation, and GitHub uses GitHub to document GitHub. Very meta!
At Red Hat and other large enterprises, having multiple products to document as well as writing teams to wrangle means that we need some extra checks and balances to ensure our documentation is sane during all development stages. Thankfully, we have passionate and talented people with some serious open-source-powered creativity that not only improved our internal processes, but also help us align as many toolchains as possible with those used by open source projects that we support.
This is how we ended up deploying continuous integration with Jenkins (we can haz CI for docs!), which upon every commit not only checks the entire product documentation library for broken links and other errors, but also produces HTML and PDF output that we can view with Jenkinscat UI. Throw in a Publican-based parser that processes DocBook and AsciiDoc source files into all the outputs with a unified look-and-feel, automated publication to the customer portal, merge requests and content reviews with GitLab, and you have yourself a pretty solid toolchain.
On the automation front, needless to say that API documentation has much to thank tools like JavaDoc, Sphinx auto-doc, and AsciiDoctor. Recently, it seems that unit testing for docs is all the rage, and not just for code examples. Up-and-coming tools like Hemingway and Emender won't fix your grammar for you, but they will analyze your content and report common linguistic fails like compound sentences, ambiguous verbs, and passive voice.
Hopefully we'll see more contributions to these tools, as they can automate some of the more tedious peer review tasks and help us maintain consistency and conciseness.
Continuous delivery
Unlike its engineering counterpart, the docsphere implementation of this principle focuses more on asynchronous publication of content, which basically means that we can de-couple content delivery from software delivery.
Freedom! Freedom to publish content whenever we need to, freedom to be as agile as we can be (and more agile than our engineering counterparts, at times). Freedom to push patches to production, so to speak, and to add enhancements to previously released content.
Those who contribute to open source projects might chuckle at my excitement, as releasing a patch for documentation can be as simple as editing a Wiki page, but in the enterprise world this is a very big deal, and this approach is yet another reason to love open source companies, where the influence of the community is very much felt and welcomed.
At Red Hat, all our documentation is publicly available for official product releases on the Red Ht Customer Portal, which means that whenever we modify content, all we need to do is rebuild the book and push the fix. Content curation has become an natural part of our work, and we try to balance unreleased and released content authoring when we plan our tasks. This practice is also quite handy when one has to rush a Heartbleed or Poodle-induced documentation fix that often applies to many products, and therefore books.
How do we manage all these asynchonous publication cycles? It depends on the product and the team. Some of our engineering teams use agile-like methodologies, so the documentation teams can align their iterations with them. Some documentation teams "agiled" themselves independently of their engineering teams. Other teams aren't even using agile, choosing instead to incorporate more content curation tasks earlier in a release cycle, and release-focused authoring later on when features are ready to document.
Collaboration
"Nobody lives in a vacuum" seems to be a sentence that I repeat a lot lately, and with good reason: Without collaboration, there wouldn't be open source software. In addition to the user-focused approach of content strategy, we must take all of our stakeholders into account when we create documentation.
So who should we collaborate with? For starters, everyone involved with the software delivery. Developers, testers, product managers, designers, support engineers, translators, oh my! We're all in this together, and there's much to be gained by acting as one product team, or at least by increasing communication across teams. And let's not forget the users themselves, from open source community members to the enterprise customers and customer-facing teams.
Most open source communities already utilize code contribution workflows with varying degrees of code review and community governance, and increasingly apply these practices to the documentation as well. Projects like Mozilla Developer Network show how the open source software principles of collaboration and community are implemented in a content community, and the OpenStack community documentation landing page actually reads, "Documentation treated like code, powered by the community".
The road to content collaboration in open source project is still long (and under construction), but more about that in the next article!
The content strategists at Red Hat now hold a formal seat and a vote in all release planning and product management meetings, alongside representatives from every role in the release process. In addition to internal stakeholders, we also implemented closed-loop programs collect feedback on our documentation, both directly from the customers or by collaborating with technical account managers, support delivery managers, and other customer-facing teams.
This type of customer collaboration is fairly new to us, but I'm confident that it will help us to optimize our content strategy planning and, when paired with the continuous delivery principle, will allow us to quickly deliver content enhancements and fixes to our customers, who are evolving from users to contributors.
What's next?
Now we have most of the pieces of the puzzle; we convinced our managers or project board that valuable content is better than comprehensive content, and we set up all the tech to support smooth content delivery. All that's left is to get some folks writing content, right?
Well, that depends. When your job title includes the word "writer" in one way or another, that's kind of expected of you. But how do you take on a fluctuating army of open source contributors who basically volunteer their time to code for your project and ain't got time, motivation, or confidence in their language skills to write all these docs you keep talking about?
In the next article, I'll aggregate some efforts from around the docsphere and share a few of my own moderate-to-crazy ideas about this. In the meantime, I'd love to hear some of your ideas and stories about how you implement DevOps practices in your content authoring!
Dish
This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us.
1 Comment