Less is More: Our Journey to Leaner, More Accessible Technical Documentation

Home/Publications/CIDM eNews/CIDM eNews 03.16/Less is More: Our Journey to Leaner, More Accessible Technical Documentation

Amy Flanagan & Lucinda Metzger, CA Technologies

Abstract

Learn how CA Technologies has embraced the DocOps content strategy, which emphasizes lean, accessible content, supports Agile, and promotes collaboration. We describe a content transformation in which we eliminated nearly half the pages from an 800-page doc set, improved the remaining content, and still met our other project deadlines. In doing so, we achieved a 42 percent word-count reduction.

Starting Our Journey

In today’s application economy, software users are expected to do more work in less time. They want easy-to-use, intuitive products. However, complex products continue to benefit from documentation that is concise, searchable, and easily available online. Users no longer need (or want!) GUI-based instructions that describe every window and field. Tech writers, too, need to accomplish more work with fewer resources. Continued rapid technological advances also render content obsolete more quickly than ever before. Additionally, with the increased focus on Agile development, the speed at which content must be created has increased dramatically. Consequently, technical writers must learn how to use dynamic authoring strategies to develop and deliver content in new ways.

Applying the DocOps strategy to existing product documentation involved migrating it from a PDF-based model to an online, wiki-based model, which supports collaboration with internal stakeholders and customers and allows for real-time updates. As part of the migration, we applied lean principles and reworked the content to optimize it for an online delivery model.

This particular migration was challenging because the existing content was not suited for online delivery. Over the years, writers with varying degrees of product familiarity and writing experience had worked on the content. Large portions of the documentation followed outdated industry standards. Much of the content was redundant, unnecessary, or incomplete and confusing.

Our biggest challenge was to rework the content to embrace minimalism. The benefits would be significant:

  • Improved content quality
  • Improved content findability due to the better organization and smaller content footprint
  • Reduced content maintenance time
  • Decreased translation costs

We addressed this challenge by developing a migration plan that enabled us to resolve content issues while also decreasing the word count. The strategies that we used can be applied in whole or in part to any content reduction strategy.

Planning the Work

We began with a high-level content assessment—comparing the tables of contents in the existing documentation and reviewing the chapters. We discovered that one guide contained a 45-page appendix that paraphrased content from other chapters. We discovered another set of lengthy procedures that was repeated three times in various places. In addition, many headings indicated overlapping content that could be combined.

We created a plan that focused on how to reduce the content and organize the remaining content in our online delivery model. For this project, we used a spreadsheet to group the work by chapter, but we also could have grouped the work by product function or other logical theme. The spreadsheet indicated which content to combine and which would remain separate. We used color coding to indicate the amount of work that each section needed and flagged areas that would require input from a subject matter expert (SME)—see Figure 1:
Figure1

Figure 1: The spreadsheet included columns to track time estimates, actual hours spent, and who was working on each chapter. We also inserted comments to identify content that belonged elsewhere, duplicate content to remove, and so on.

This spreadsheet was posted to an internal team wiki page where we could access and update it.

Finding the Time

As part of the planning process, we worked with the product team to integrate the content migration with the development schedule. Our company uses an Agile methodology, so this integration consisted of creating sprint stories and adding them to the scrum team’s backlog.

Having these stories in the backlog ensured that they were included in the team discussions when we planned our work for each sprint. We pulled these content migration stories into sprints based on our overall workload.

We also tackled low-hanging fruit during spare hours. For example, we removed unnecessary screen shots and field descriptions that were already available in online help. By addressing the obvious problems first, we “reduced the noise” in the content and saw where we needed to focus. Related or duplicate information became apparent, as did content that was in the wrong place.

Reducing Word Count

The content received one of three treatments:

  • Full rework
  • Partial rework
  • Minimal rework

Ideally, we would fully rework everything. Since time and resources did not permit this goal, we used the data from our planning spreadsheet to shape our approach. Some content (especially reference material and messages) required very little rework. Other areas were in poor shape. We did a full rework on as many of these as possible. Overall, about 25 percent of the content was fully reworked, about 50 percent was partially reworked, and the remaining 25 percent was migrated with minimal rework.

Full Rework

A full rework required product knowledge and the expertise of our SMEs. In addition, we used an automated tool to help ensure compliance with our standards and identify redundancies.

This level of rework involved the following tasks:

  • Revise the content for completeness, logical flow, and lean content principles
  • Interview SMEs to address technical inaccuracies
  • Verify the updated content against the product
  • Submit the reworked content to our SMEs for review

Partial Rework

The partial rework focused on making improvements that did not require SME input. A partial rework required some product knowledge, but some of these tasks could be done without any product knowledge. This partial level of rework involved the following tasks:

  • Rearrange existing content to improve logical flow
  • Apply lean content principles
  • Add missing information where possible
  • Combine over-explained content
  • Remove unnecessary content

Minimal Rework

A minimal rework focused on cosmetic changes. Any writer could perform a minimal rework, even with no product knowledge.

This level of rework involved the following tasks:

  • Fix obvious problems, such as strange formatting and obsolete references to chapters or guides
  • Remove unnecessary screen shots, duplicate content, and code samples that were available within the product

In the End. . .

We got there.

Completing this project took the two of us approximately 330 hours over seven months. This total includes the revisions described in this article and the administrative tasks associated with the actual migration. When we compared our migrated content against the original, we found that we had reduced our word count significantly.

From project design through execution, we adhered to the principles of the DocOps strategy. Our revisions focused on transforming legacy content into a lean, searchable, organized online model. We collaborated with our SMEs and adjusted our workload and approach according to the Agile methodology.

The response from our users has been positive; collaboration is faster and easier than ever before. The dynamic nature of our wiki-based delivery model makes it easy for us to respond quickly in an Agile environment. Going forward, we’ll continue to work with our internal stakeholders and customers to improve the content and help them find what they need, when they need it.

You Can Do It: Best Practices

You can apply our strategies in whole or in part to any content reduction project. Here are a few tips to get you started:

  • Plan the work, but be flexible about how you implement the plan.
  • Partner with your development team to implement tool tips and intuitive designs. Doing so helps reduce the need for traditional content.
  • Share the plan with your stakeholders and request their input.
  • Break the work into manageable and trackable tasks.
  • Integrate your work into the development schedule.
  • Last but not least, just jump in and start! This project was large and challenging. But when we started, things fell into place. As we removed unnecessary content, we could see what was left with better clarity and decide what to do with it.

We did it, and you can too. Good luck!

About the authors

Amy Flanagan is a Principal Information Services Engineer at CA Technologies. She has been with CA for 6 years, documenting a variety of database performance management products.
Amy.Flanagan@ca.com

Lucinda Metzger is a Senior Information Services Engineer at CA Technologies. She has been with CA for 9 years, documenting various products that target database performance, backup, and recovery.
Lucinda.Metzger@ca.com

www.ca.com

We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close