“In 20 years, I’ve never seen such a creative, inventive approach to creating technical content. I was stunned by what I saw.”
—PG Bartlett, introducing Jim Turcotte and DocOps in a recorded presentation
We live in the application economy. Business is driven by a connected, application-centric world where customers experience and interact with brands through software applications more often than through people.
Do you deposit checks with mobile banking? Automatically regulate the temperature of your house remotely via a Nest thermostat? Stream your favorite shows through Netflix? To succeed in this new world, companies must deliver superior experiences that engage their customers – experiences with software applications. Ideally, those applications are supported by intelligent content.
This article walks you through these main points:
- Why content velocity is critical
- How the legacy approach fails to meet customer needs
- What DocOps means
- How DocOps supports intelligent content
- How our team created DocOps
- How we put DocOps into practice
Our DocOps landing page (wiki.ca.com) with product drop-down list
This content adapts to the customer’s device of choice.
Why content velocity is critical
In order to survive and thrive in the application economy, companies are turning to high-velocity software-development practices, which are sometimes called DevOps – Agile methodology on steroids. DevOps is quickly becoming the development standard in the application economy. This approach is becoming popular since it leverages automation, continuous testing, and increased collaboration.
Software releases that used to take months are now done in weeks or even days.
While software-development practices have made strides toward efficiency and velocity, the management of content – especially software documentation – lags. Many companies still create documentation using clunky writing tools that only expert technical writers can use – tools that lack the agility required to keep pace with today’s high-velocity development processes. (Instead of technical writers, we use the term information engineers. For this article, I’ll stick with the more common term.)
Customer-support staff members often address documentation bugs by creating knowledge-base articles using formats and processes separate from the original documentation. These separate articles need to be shut down – and this is an exciting opportunity.
The siloed approach to software documentation is slow and inefficient, resulting in a poor customer experience. And it’s not competitive in today’s market. We need to update the original topic. Like a fine wine, the original information needs to get better with time.
How the legacy approach fails to meet customer needs
Going back a couple years, CA Technologies (the company I work for) faced issues associated with stagnant, siloed content. Our software development teams were becoming more agile, but our inability to develop and deliver technical content at the same agile pace was becoming a drag on the software R&D ecosystem. At that time, I was the executive for Technical Support, where I experienced firsthand our customers’ inability to find answers due to challenges such as content redundancy and content-delivery latency.
At about that time, I moved from Technical Support to lead our R&D Information Services team – a combination of technical writing and globalization teams. We spent several months assessing the current tools, processes, and data. Like most technology companies, we created our content in silos.
Specifically, technical writers shadowed developers, using typical writing tools that led to the publication of content when products went live. Customer Support, Services, and Education teams followed up by creating additional customer content. Unfortunately, that content ended up often being redundant, or using similar themes in different formats and – almost always – in different repositories.
In other words, when it came to documenting the applications, the company’s left hand didn’t know what the right hand was doing. To make matters worse, technical writers were given little analytical data as to how – or even whether – their original content met customer needs.
Our team needed a new approach. We needed to determine how content should be created in this new application economy. We needed to base documentation efforts on the same philosophy as DevOps, creating content in a collaborative, continuous, agile fashion.
DocOps was born!
We didn’t call it DocOps right away. At first we referred to the project by a generic code name. Then one day, as I was explaining to one of my team members about the goal of emulating the DevOps approach, she coined the term DocOps. It stuck. In fact, this term is starting to be used by other companies that are excited to use the same collaborative approach to creating content. Companies that are already using DevOps understand the connection and need for DocOps.
What DocOps means
DocOps means crowdsourced, single-sourced software documentation housed in a central repository – in our case, a wiki-based platform. DocOps means documentation that is developed and released in lockstep with DevOps applications. DocOps means that software companies can no longer afford to wait for code freezes or localization drops at the end of the development cycle; product information has to be developed using an Agile approach with tools that enable collaboration, agility, and continuous release.
Atlassian has referred to DocOps as “the kick-ass cousin of DevOps.”
DocOps magazines on the Flipboard social media platform
This content is delivered to customers wherever they are.
How DocOps supports intelligent content
When we were setting up a new platform for DocOps, we knew it had to support collaboration and analytics. And we knew it had to enable us to create intelligent content. Our DocOps system supports tagging, content reuse, and discovery. Beyond that, its adaptability is exciting our customers.
For example, we created “technical cookbooks” for over two dozen key products on a social magazine called Flipboard. The content is the same content that was presented to the customer from DocOps via the web or product interface. Customers flip through one of these cookbooks to pick up tips and tricks on the products they are using.
DocOps has enabled us to reuse content in various deliverables, getting it out to our customers wherever they need it.
How our team created DocOps
Our DocOps pilot project was designed to enable collaborative authoring. We put in an Atlassian Confluence wiki due to its extensibility. Using third-party plug-ins, we created a collaborative authoring environment with basic documentation functionality including the ability to manage multiple software versions. The key was to make collaboration the primary focus over heavy-duty, difficult-to-use content management systems and tools.
Being a large global company, CA Technologies needs to internationalize its products and content. So we decided to automate content translation by linking our Confluence wiki via APIs (application programming interfaces) to Lingotek, a cloud-based translation manager.
Doc Ops and translation efficiency
Serving as a gateway for translation, Lingotek transmits and manages the content moving from the wiki to our translation vendors and then back to the wiki, based on a workflow set up by CA Technologies teams.
Finally, we built a dashboard with customer-usage analytics. Viewable only by CA employees, the dashboard analytics help writers act quickly on customer comments and analyze content trends.
At the conclusion of this pilot project, we had the core DocOps platform, which enabled collaborative authoring, supported on-demand translation, and provided much-needed agility.
With our new tools and processes, we could publish and translate the documentation in minutes.
The DocOps platform we created is extensible; we can easily add plug-and-play components. For example, we are adding Jive (a communities platform), Marketo (a marketing-analytics tool), and Microsoft Azure ML Studio (a machine-learning capability). CA Technologies product content on the DocOps platform is also now contextually linked to product user interfaces.
Imagine using software that presents instructional content directly related to the function you are performing at any moment – in whatever language you need.
Contextual, language-sensitive content
DocOps delivers documentation in the right language (when available).
The top screenshot shows English; the bottom shows French.
How we put DocOps into practice
How does this all work in practice? Let’s start with an internal view.
- Authoring has become more of a crowdsourced effort. Technical writers no longer act as siloed authors. In addition to authoring, they can curate content from other authors with whom they collaborate: support staff, developers, product managers, and other stakeholder contributors.
- Content updates are easier and faster.
- Translation is executed in near real-time after each Agile development sprint. And we’re seeing significant cost savings; we’re on track to reduce translation costs by 33%.
- Content is made public at the time software is released. It is then updated continuously by technical writers, support staff, and other content contributors throughout the life cycle of the product.
- All documentation is stored in a single wiki instead of multiple, separate content repositories or even Help in the applications. We threw out our old document-management system. The wiki provides a single source for all product-related information. Topics can be updated on demand, based on customer requests, incoming issues, or analytics.
Externally, customers have the following advantages:
- They can now access DocOps content on the web (directly or via any search engine).
- They can access the content via mobile devices or desktop computers (due to responsive design – and we plan to make the content fully adaptive in the future).
- They can access content directly from their application in the desired language (when available).
DocOps content on the web
Customers can now access our documentation in a browser either directly or by searching. Roughly
10-15% of our customers now come from Google. Now 90% of our content is available to the public
(as opposed to 20% when we started two years ago).
Summary
If your company wants to improve its customers’ experiences with software documentation – or any kind of content – in today’s application economy, I recommend following the principles that have worked well for us at CA Technologies:
Collaborate: Encourage people to work together across content silos. Experts throughout the enterprise can contribute.
Update continuously: Content must be updated efficiently, accurately, and quickly throughout the life cycle of the product.
Use analytics: Your customers are talking to you through content analytics. Study and use the analytics data you gather to improve the customer experience.
Stay agile: Enable near real-time content updates in all languages (up to 20 languages per product, in our case).
Learn more
For more on DocOps, check out these articles and videos:
- DocOps: Interview With Jim Turcotte, Tom Johnson, “I’d Rather Be Writing” blog
- Learn How CA Technologies Broke the Rules – Their DocOps Approach to Agile Technical Content, Jim Turcotte (YouTube recording of a presentation)
- Cloud-Based Documentation at the Speed of DevOps, Andi Mann, CA Technologies “DevOps.com” blog
- CA Technologies Enables DocOps, James Turcotte, LinkedIn post
Title image courtesy of Joseph Kalinowski, Content Marketing Institute
