The DocOps Trend: Applying Agile and DevOps to Technical Documentation
I bring an excerpt of this article to you courtesy of Will Kelly, as I think it brings to you methods and experiences from other technical writers around the world. You may view the original article here.
The advances and benefits in Agile programming and Agile project management are making headlines and grabbing a lot of attention these days. But what about technical documentation?
While one of the principles of the Agile Manifesto is “working software over comprehensive documentation” you can’t escape the need for customer-facing documentation.
In response to all this, there’s a movement called DocOps (Documentation/Operations) that takes on the challenge of applying Agile and DevOps principles to developing and managing technical documentation. As it turns out, varying definitions of Agile technical writing predate the DocOps concept.
The DocOps movement can be an integral part of managing and delivering successful projects. Your technical documentation efforts don’t stand a chance of hitting deadlines, maintaining quality and technical accuracy if they follow a separate track from your Agile development efforts.
The story behind DocOps
CA Technologies is an early DocOps thought leader and practitioner. Jim Turcotte, a CA Technologies executive, introduced DocOps to the world in a LinkedIn post last year entitled CA Technologies Enables DocOps. This article gave an overview of how CA Technologies is creating a “content supply chain” to help their technical writers keep pace with Agile development. Turcotte later followed up with another LinkedIn post, DocOps – How CA Technologies Got Started!, in which he gave an overview of the platform and tool choices behind their DocOps-driven technical content publishing operation.
Here are some key principles behind what DocOps does:
- Creates a continuous technical documentation flow, similar to how continuous integration creates a continuous flow for software developers.
- Moves all documents into a cloud-based collaborative platform like a wiki, which becomes the primary publishing and delivery platform for user documentation.
- Aligns common Agile tools with a documentation publishing platform.
Beyond these points, DocOps applies analytics and reporting behind the publishing platform to monitor which content is performing better than others. As project management and enterprises become more data driven, I see this as a strong selling point for DocOps because it enables technical writers to manage content better. They can focus their development efforts on content that readers need versus that which the documentation team perceives as reader needs.
During later media interviews, Turcotte also mentioned that CA’s writers constantly “curate” technical content throughout the product lifecycle. Content produced in a DocOps environment continues to mature. For example, when the support team or a sales engineer finds a documentation error (think a doc “bug”) they work directly with the writers to fix and then republish the documentation.
Agile technical writing best practices
The term Agile technical writing has been around for a few years and can mean different things to different people.
Tom Thompson over on TechBeacon wrote about Why Agile Teams Should Care About Documentation. He suggested that the development team has little reason to care about documentation because it’s usually handled in the final phases of the project, along with testing and quality assurance.
He emphasizes that the documentation must be baked into the Agile effort. Making the recommendation actionable requires a technical writer to do the following:
- Align technical documentation with the business.
- Work with project managers and other stakeholders to plan documentation in parallel with software development.
- Participate in scrum sessions representing documentation needs and status.
- Become as self-sufficient with the technology that the developers are building.
One chip for technical writers to cash in with Agile developers is to find bugs and UI issues in the software. To do this properly, technical writers should have access to the development team’s bug tracking software so they can perform the entry on their own.
Solving PM challenges with DocOps and Agile technical writing
Project managers in Agile environments might need to ensure that documentation stories make it into sprints. This way, developers capture what they built before they move onto the next sprint. While this seems contradictory to the Agile Manifesto, I think there’s room for creativity here, such as:
- Engineers can capture only the key details, especially when it comes to an API interface.
- Automated tools for API documentation can be a mixed bag, but worth exploring if you can integrate the automated tool into your build process.
- Together, the product lead, project manager and technical writer strategize ways that the technical writer can keep pace and even work ahead of the development team.
The potential introduction of analytics and reporting on a backend of a DocOps publishing platform means that the project manager and technical writer will have to manage the analytics, interpret the results, and determine how/when the technical writer improves documentation based on the results.
Technical writing in an Agile world
DocOps and Agile technical writing feel like seeds of a larger and much-needed movement for the Agile community at large. There’s even enough information and inspiration online for an Agile development organization to adopt DocOps and Agile technical writing best practices to fit your organization. Why not give it a try?
If this article got you thinking, and you’d like to learn how Agile works for different teams, download our eBook, “Agile for Everyone.”