Welcome back to this (semi-)regular column where I attempt to answer questions about DevOps, especially in larger enterprises. This time I address a vexing issue facing many large enterprises – how to make sure downstream processes move as fast as development and operations:
Q. In my enterprise we are getting faster at releasing code, but we are still slow to update and translate downstream product documentation. How can documentation and technical writing be optimized as part of a DevOps approach?
As I have said before, you can ask me any question you want (in the comments below, via e-mail, or on Twitter), but that doesn’t mean I know all the answers. If (when) I don’t know, I have promised to try to find someone who does – and this is one of those times.
This question stumped me, so I asked around to find some insight into this issue. As it turns out, my company (a large enterprise, building out our DevOps capabilities, developing and operating new software every day, in many different languages, across about 40 countries worldwide) is working with what we think is an answer to this question. So I asked my colleague Jim Turcotte to explain what we are doing to address this problem. Here is what he said:
The problem – serial downstream processing
I know exactly the problem that this writer is facing! We have been wrestling with this ourselves. The problem is that with current industry practice, a team of technical writers shadow developers to document the latest product functionality. By the time product is delivered, it’s a mad dash to publish the PDF/HTML. Then, to make matters worse for international customers [our software users], it may be days or weeks before localized [translated] versions of content follow. It’s a slow, tedious, serial process that ends up being a rush to the content finish line every time.
To make matters worse, both documentation and code are typically “thrown over the wall” for Support to discover and address bugs. Documentation bugs are often handled by Support engineers writing dozens of knowledge docs. The end result is that skilled Support engineers are often diverted from addressing customer issues, to updating documentation. We then expect users of our software – our customers – to search through the product documentation and sometimes hundreds of Support knowledge documents to find answers to their questions—not exactly an optimal self-service experience!
Introducing a cloud-based collaborative approach
Something we have started doing to address this concern is by applying what we call ‘DocOps.’ It is a continuous content supply chain that connects all the stakeholders, and which is agile and collaborative. In this way, our approach mirrors many of the characteristics and culture of DevOps.
Instead of waiting until code is complete before starting on documentation, multiple writers “curate” content throughout the product lifecycle. Instead of producing static, standalone knowledge documents in PDF (or even HTML), we use cloud-based documentation, wikis, forums and chat groups. Instead of a single one-time effort, original content topics are matured continuously in a collaborative effort. Instead of channeling documentation through a single technical writer, we allow developers, operations, support, and even technical field staff [pre-sales] to curate documentation.
On-demand translation is performed as needed using local cloud-based translation services. Highly automated workflows determine which vendors will be used for each product and language. The platform senses the customer’s language preference and automatically pulls up the content in the language they prefer.
Then there’s online help. With the approach, we provide contextual help by linking content directly to product UIs. This allows customers to access additional sources of information like education courses and discussion threads all from the same source. Customers no longer have to log into multiple systems or sites to find the information they need to be successful.
Benefits of the new approach for end-users – and for us
For end-users, collaborative curation ensures documentation is always crisp and relevant, reducing the age-old problem of large quantities of duplicated knowledge/content. Customers who need help using a product are always able to find and use the latest curated content – in their language, relevant to their experience. Customers can also now access not only the developer’s original instructions, but also knowledge from other product experts, colleagues and peers.
For us, we can use its analytics to provide real-time operational feedback, so technical writers can make updates on the fly to further improve the customer experience. The new approach also enables us to close the feedback loop, connecting end user questions with engagement and lead generation tools such as Marketo, marking the first time product documentation can also be leveraged as a serious sales tool.
The old school Content Supply Chain cannot support the business agility that DevOps requires to be successful. The new documentation approach solves that. It was conceived and built around the need for an improved customer experience with product information. Do you really want to maximize your DevOps platform? Support the content with the new approach for the ultimate agile experience.
Jim Turcotte is a Senior Vice President with CA Technologies and the Business Unit Executive for its Information Services team. For more information about DocOps, follow him on LinkedIn Pulse.
