kosmin - Fotolia

Get started Bring yourself up to speed with our introductory content.

Make DevOps documentation an integral part of your strategy

DevOps is for the writers on your team too. Will Kelly offers on point advice on how to easily bring technical writers along during a DevOps transformation.

Even though there are technical writers who specialize in software development documentation and others who specialize...

in operations documentation, the role hasn't figured into the overall DevOps discussion to date. Customer demand for documentation doesn't stop, however, so it's still up to organizations to prepare their writers for DevOps documentation.

Here are some ways to add a technical writer to your DevOps toolchain:

Customer-facing and high-level design documentation

John Yung, founder and CEO of Appcara, explains that while in the past technical writers had specializations such as hardware, software, or IT infrastructure, DevOps and agile methodologies are changing that. There's no longer time to produce formal and detailed documentation.

Mike Kail headshotMike Kail

"I see the role of tech writers shifting more to customer-facing documentation and high-level designs that cover across multiple areas," Yung said. Such a change means technical writers will need to understand the project and its technology broadly. They'll need to participate in project meetings instead of interviewing architects and developers individually.

Yung recommends development managers provide more technical training for tech writers looking to tackle DevOps documentation, so they can understand the high-level scope, components and other points of a project.

A high-velocity publisher

Just as developers are changing up their toolchain for DevOps, technical writers need to do the same. Doing DevOps means the days of long-form print or even PDF technical manuals are over. Complex online help systems may go by the wayside for some applications, as well for reasons of speed and velocity.

AWS is probably moving at the highest velocity of anybody, and their documentation is always up to date.
Mike KailCTO, Cybric

Development managers can work with technical writers to put the right online publishing toolchain in place to keep pace with the rest of the team. For example, technical writers can use an external-facing wiki or content management system to publish feature-level documentation. Updates and additions to the DevOps documentation can take place during and even after the build cycle. Customers would access the content from the application via a link. Organizations can even set up a publishing strategy that outputs content from that wiki for other documentation and fulfills marketing content requirements.

We've seen and heard of this kind of publishing toolchain before. CA started a DocOps trend -- that applied DevOps to documentation practices -- back in 2014 and 2015. A DocOps-like strategy could bring writers and DevOps documentation more easily into the discussion.

Shift your technical writers left

Mike Kail, CTO of Cybric, thinks technical writers need to become part of the whole shift left movement and inject themselves into the development cycle early on. Building upon Yung's advice, Kail advised that technical writers join the daily scrum.

"They should have access to JIRA or whatever platform the team is using to collaborate on the backlog and current tickets, so they know what's happening well before it's ever delivered," Kail said. "As you move to continuous delivery, they need to be aware of that and get notified so that they're prepared."

He points to AWS as an organization that gets DevOps documentation right in a continuous delivery environment.

"They have Jeff Barr, their chief evangelist, who pumps out blog post after blog post, which then, in parallel, fuels their documentation, which is always up to date. So, it's possible," Kail said. "AWS is probably moving at the highest velocity of anybody, and their documentation is always up to date, so it's possible to get it done. It's always the cultural transformation that has to happen versus technology and process."

AWS is a prime example of how organizations can use technical writers and the content they produce for thought leadership and product evangelism. Such a shift is possible but requires cooperation from marketing, product management and development -- plus a publishing toolchain in place.

Create your own DevOps technical writer

Because it's still early in the DevOps discussion about technical writers, by all means, you should take advantage of the situation to write a DevOps documentation future for your technical writers. While DevOps is already driving quality assurance roles, the technical writer role is probably open on your DevOps teams.

Dig Deeper on Modern IT Operations Skills