Q&A: Technical Writing and DevOps

Question

If you were hiring someone to come on board as a technical writer for a DevOps team, what would you want them to know coming on board?

Answer

First of all, it would be great to have a dedicated writer assigned to a DevOps team. Having someone to assist with professionally documenting the environments and applications owned by the team would go a long way for everyone, including the customers.

So to keep things in scope, I’m coming from the perspective of bringing on a technical writer specifically for support documentation for the internal team and user guides for any customers or third parties that might need to interact with the application.

The DevOps Lifecycle

First of all, I’d expect my writer teammate to be familiar with each of the stages that make up the DevOps lifecycle. While it's almost always shown as an infinity loop, different interpretations show this cycle with different numbers of stages. I stick with these eight stages: Plan, Code, Build, Test, Release, Deploy, Operate, and Monitor.

So the writer should know the goal, inputs, and artifacts of each of these stages and how to document the processes associated with each if needed.

Ideally, I’d focus them on the Operate stage because a lot of the internal and customer facing documentation would be associated with that stage. Basically, know how the application and/or infrastructure work and capture the details that an operator or user needs to know to be effective.

Automation and Tooling

Teams should always be looking for ways to tighten up each stage of the DevOps lifecycle. Well placed automation is usually the key to that. It would be beneficial to the team if a writer was able to interact with the tools and procedures used by the team and share points where automation could be applied. Even better if they can research new tools and methods for automating and share an executive summary with the team or even a proof of concept that the team can experiment with. Basically, anything that brings value to the team that helps them work smarter and more efficiently would be an asset.

Now, with that said, I would not expect anyone to know every tool. But having some experience with build tools, or knowing a scripting language, or even knowing how to incorporate bots into tools like Slack would be a nice touch. Often, being efficient with and knowing how to operate one tool makes it easy to pick up another tool from the same category.

Testing

It would be a bonus if the writer could participate in testing, particularly from the user’s perspective. Working from that angle, the writer could help fine tune any documentation or instructions users might need to get started or provide details on places where they might get stuck. At the same time, they would be close enough to the development or operations folks to provide trusted feedback.

In the end, each team is different and the way they work with a writer will be different. But I do believe that having some of the knowledge mentioned above will go a long way for a technical writer working in a DevOps role.