It's common for enterprises to leave the technical writer's role out of the DevOps discussion. Even the marketing department joins the discussion in some DevOps-first organizations—so why not the writers?
Our industry doesn't ask enough of its technical writers. Documentation is an afterthought. Companies farm out technical writing to contractors at the end of the project lifecycle. Corners get cut. Likewise, technical writers don't ask enough of their industry. The expectations for the role vary from company to company. Both circumstances lead to technical writers being left out of the DevOps discussion.
As your organization matures its DevOps practices, it's time to revisit the role of your technical writer.
Recast your technical writer for DevOps
I remember one of the first agile projects I ever worked on, back when I was still writing technical documentation. One of the other writers on the team had a hard time grasping the fact that we had to write about a product that wasn't 100% complete. Those days are gone. Thank you, DevOps and agile.
It's time for organizations to revisit how they hire technical writers. Throw out your waterfall technical writer job description. Right. Now. I've always divided up technical writers into operations technical writers, who document infrastructure, and software development technical writers, who document software development. The writers flit back and forth. But, finding a technical writer with a grounding in software development and operations can be helpful for staffing a technical writer position on your DevOps team.
DevOps means you may need to make changes to your standard "corporate technical writer" job description. For instance, weigh software and operations documentation experience higher than before because the flexibility will only help your team. The same goes for writers with experience creating more modular online documentation using tools such as Twiki or Atlassian Confluence.
DevOps also requires technical writers who can be full participants. Writers can no longer add value if they expect features to be complete before they get involved. Look for writers with experience driving documentation efforts. Your goal should be to find a technical writer who can work with fewer dependencies that you can plug into various parts of your delivery cycle. This can be easier said than done when it comes to hiring. The only advice I can give is to color outside the lines of the traditional technical writer role and be prepared to pay for it.
Another skill to seek in a technical writer for your DevOps team is collaboration platform management. Adding that duty to your technical writer job description takes a non-critical task off of a developer's to-do list.
The DevOps technical writer should take the same onboarding path as the developers and other project team members you bring on board. Give them access to the systems they need to document in a sandbox running the same builds as everybody else.
Measuring the technical writer's success in a DevOps world takes on some new shades of meaning. You can tie your online documentation to analytics to track readership. You also need to track the technical writer's work the same way you're tracking developers' work. Documentation has bugs, too.
Retool your documentation process
Technical documentation has to take a more toolchain velocity-driven approach to keep pace with DevOps. There have been some stops and starts in rethinking documentation publishing in a high-velocity DevOps world.
A movement called DocOps, out of CA (now part of Broadcom), brought together technical documentation and DevOps practices, but the original team behind the concept appears to have moved on. The effort fizzled out, but I still recommend researching it online. You will get the CA.com documentation subsite in your search returns. It's running on Atlassian Confluence with CA branding and other customizations. It's been migrated from the more traditional documentation formats of Webhelp and PDF to separate documentation away from the applications they support. While the development team and documentation still have to be in sync for releases, they aren't as dependent on each other for maintenance and updates.
Content-as-Code also holds value for your move to a more DevOps-friendly documentation strategy. It uses software engineering practices to support content reuse. It breaks away from the traditional content management system (CMS) model; it uses Git for content versioning, and technical writers and other content authors use Markdown for authoring. Content-as-Code as a development model supports static website generators such as Jekyll and Hugo with interoperability with CMSes.
Whatever direction you choose for publishing your documentation, it's important to do the upfront work. Start with a small proof of concept. Experiment with tools and workflows. Involve your development team in the initial process to get their feedback on the new publishing model you are building. Make sure to document your publishing tools and workflow, just as you've done with your DevOps toolchain.
The DevOps technical writer's time is now
The cultural and technology transformation DevOps brings to organizations means there could be more work for an experienced and well-placed technical writer. Just as you brought your developers and system administrators into the DevOps age, do the same with your technical writers.
How is your organization adjusting the technical writer role for DevOps? Please share in the comments.
1 Comment