Improving Legacy Content: A Common-Sense Approach
Contents
Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.
Introduction 
When faced with large amounts of outdated and poorly structured legacy information, you may not know where or how to start making improvements. But, you can produce improved content that your customers will appreciate and use by getting to know your audience, learning your product, and bringing together reliable sources of information. This article describes how these practical methods have been successfully implemented in various types of environments.
As technical communicators, most of us have started work on a new job or project, reviewed the existing product documentation, and quickly discovered that we must do more work than simply making updates for new or changed product features. We know the feeling of panic that strikes when working with deadlines that account only for required new content. Often, management is unaware of the problems with legacy content, which makes our task even more daunting.
But, if we, as technical communicators, want to be appreciated as valued professionals who contribute to our customers' success and our company's bottom line on a consistent and ongoing basis, we must take responsibility for all content that exists for our products and ensure that it is accurate and useful. And, yes, this does seem impossible sometimes. The good news is that there are always people who care about customers as much as you do and who are willing to help.
In this article, you will discover how to overcome the challenges by using a practical and proven methodology that I have developed by listening to and learning from many different talented individuals in various roles throughout my career as a technical writer. In addition to describing the methodology, this article walks you through two separate case studies that show you how to implement the necessary steps even in the most difficult of circumstances.
When you approach difficult projects like the ones described in this article, remember that your greatest achievements always come from teamwork. And, the most productive teams are often informal ones.
Methodology
When you know that you need to overhaul large amounts of outdated legacy content, you should:
- Quickly learn the product and understand the obstacles that customers face when using the product.
- Recruit key internal resources-those individuals who work closely with customers and are invested in ensuring repeatable success for those customers.
- Identify and plan a pilot effort that will enable you to quickly show results.
- Use the momentum of the pilot project to secure the resources and tools that you need to completely reorganize and rewrite all legacy information.
The following sections describe each principle of the methodology. Following the descriptions are two case studies that illustrate how the methodology has been applied in two separate projects for two different companies. You can use the examples to gain an understanding of how such an approach might work in your own environment.
Learn the Product and Understand Pain Points for Users
As technical writers, we're all familiar with the need to analyze our audience and their tasks. What I have discovered over the years is that this analysis is much more valuable when you have an opportunity to directly interact with customers. Recognized experts recommend direct interaction and contact with customers whenever possible. However, this can often lead to somewhat stilted interviews and formal exchanges that do not produce the type of insights that we need to truly understand the user's perspective.
To quickly learn the product and, at the same time, learn about the obstacles that your users face, try to attend training for the product with new or existing customers. When you do this, you sit in a room for days at a time with people who are currently using (or soon will use) your product to achieve a certain set of goals. It's an ideal opportunity to hear about their frustrations and confusion first hand. The conversations are not filtered and not focused solely on the documentation. This is important because customers are focusing on what they're trying to accomplish with the product, they have an expert on hand to guide them and answer their questions (the trainer), and you can watch, listen, and determine whether they have the information they need to accomplish their goals. Everything you learn can be applied to improving legacy content and writing effective content for new features.
Many companies now offer product training through web-based virtual classrooms, which should increase opportunities for technical communicators to participate because there are no travel costs involved and there are no issues with available seats. However, if you cannot attend product training, you can still collect this type of information by working with trainers, support, and services personnel who have regular contact with customers. While learning the product, make a list of the tasks that you believe customers need to perform, jot down your questions and any areas that are confusing, and consult with individuals from customer-facing departments to see if your ideas and perceptions are accurate. You should also interview these individuals and collect any data that they have regarding the most common questions from and problems reported by customers.
Recruit Cross-Department Resources
When working with individuals from customer-facing departments to understand user tasks and common pain points, it is usually easy to identify those co-workers who are truly invested in ensuring repeatable success for their customers. Here are some common characteristics and behaviors to look for:
- Are often recognized as heroes who work on site with customers to ensure the success of important projects
- Are tired of repeatedly answering the same questions and performing the same tasks so have started to write and post their own Q&A and how-to documents to save time
- React enthusiastically to any queries for information to fill in gaps in current documentation and/or volunteer to share documents that they have written to be used as source for product documentation
- Understand that heroism does not scale and that the key to long-term company-wide success is the teamwork necessary to ensure customer satisfaction
Recruit these individuals to help you with your pilot project. They will be valuable reviewers and advocates as you move forward.
Plan Pilot Project
To keep your cross-functional team invested and to provide a proof of concept to management, identify a pilot project that enables you to quickly show results. Find an area of the product that both internal and external customers have been struggling with and develop a document or some other form of user assistance that makes the required tasks easier to understand and perform.
In addition to your existing informal cross-functional team, be sure to involve product management and other key stakeholders from within your organization in this pilot project. Enlist the help of the key decision-makers in your organization in selecting the project so that they understand why they should invest the time and resources to complete it.
After selection of the topic, circulate the plan for the pilot project with stated goals and milestones. Be sure that you meet the milestones to keep everyone involved fully invested. It is extremely important that you execute to plan and also meet the stated goals. You must be able to clearly demonstrate results such as improved customer satisfaction or improved adoption.
Ride the Momentum of the Pilot Program
Based on the results demonstrated by your pilot project, roll out a similar plan for all problematic legacy content. Break your plan into phases that align with product release schedules. Ensure that you have the resources required to write new content as well as re-write and reorganize legacy content.
Involve your original cross-functional team in all plans for documentation improvements, continuing to rely on their expertise and customer knowledge when developing your outlines.
You should also continue to explore opportunities for informal and cost-effective customer contact such as user conferences, local user groups, webinars, and so on. As you develop plans and outlines for specific functionality, identify customer events that align with your efforts.
Sample Implementations
The following case studies describe how the methodology has been implemented in product documentation efforts at two separate companies. Both companies had hundreds of pages of outdated legacy content; however, the information development tools, organizations, and personalities involved were completely different.
Sample One
The company employs approximately 200 people and produces software products that enable network and system administrators to monitor and analyze network traffic. The documentation team included two writers who reported directly to the vice president of marketing. The writers used Adobe Framemaker and RoboHelp to deliver PDFs and online help.
Problems Faced
The documentation team faced the following issues:
- Customer satisfaction rating for all product documents was extremely low: 25%.
- Existing user guide and online help for flagship product covered an outdated version of the product that was totally different from the shipping version of the product.
- Efforts to update and improve the current documentation for the flagship product had to be completed within the six-month release cycle/software development effort.
- Only one new writing resource (me) was available for the effort.
Alternatives Considered
After assessing the situation, I presented the following alternatives to the product manager for the flagship product:
- Strategically update the existing User Guide by identifying and rewriting the areas that are the most outdated and error-ridden.
- Develop a new User Guide from scratch, leaving the online help, installation and administrative information, and other topics to be covered by new documents in a follow-on release.
- Create all-new documents for all areas (using, installing, and administering) by covering only the basics in each area, filling in with more detail in a follow-on release.
We decided to develop a new User Guide from scratch, leaving the online help, installation and administrative information, and other topics to be covered by new documents in a follow-on release. The idea was that it would likely be possible to produce more than just the User Guide, but we decided to focus on one deliverable as a pilot project to prove the results of our new approach.
Challenges
As a new writer for both the company and the product, I faced the following challenges:
Had to quickly learn the product.
Solution: Got permission to attend local 3-day training with customers.
No one offered this up as an option; I had to research to find the training schedule and had to contact account reps in the sales and professional services organizations to make this happen. So, don't wait to be invited to training; get what you need as soon as you can.
Had to identify areas where customers were confused by the product and identify ways to improve their experience.
Solution: After attending product training session with customers, reviewed documents and web pages developed by different professional services and support personnel. Interviewed those individuals who had taken the time to try to fill the gaps for customers with their own documents. Proposed working with them to get all information documented in one place-the product documents. So, in essence, we formed an informal team. Professional services and support folks were invested in my efforts because it helped to ease their workload and also because they simply cared about their customers.
Solution: Visited vendor where products and documents were packaged and shipped to customers to understand exactly how and what our customers unpacked and were faced with when dealing with our products.
Had to quickly produce results to retain investment from the informal team and to get product management and development management formally on board.
Solution: Developed an outline for the new User Guide, got sign-off on the outline from all interested parties, and produced a draft for review within five weeks. The new guide was task based and included the new features for the current development effort. The new guide also included case studies for customers to illustrate how to effectively use the product. Many users I met at the customer training were call center personnel who felt uncomfortable admitting their lack of knowledge about certain technical aspects of the product. Our trainers confirmed that this was often a problem at each customer site. Step-by-step procedures and the case studies all incorporated real-world examples for users with less expertise.
Results
Because of the early efforts outlined in the preceding solutions, the project progressed at a rapid rate, with invested individuals from all groups helping to confirm findings and fill in gaps so that we were actually able to deliver an entirely new document set for this product during the six-month release cycle. Because all new information was task-based; I was able to re-use some of the same content to produce online help for end users and administrators. Several individuals from across teams came together to solve a long-standing problem with the product documents. This effort resulted in a big jump in customer satisfaction from 25% to 85% for the flagship product.
Sample Two
The company employs approximately 250 people and produces software products that enable business analysts and developers to automate business processes. The documentation team includes two writers and a documentation manager who serves as an individual contributor on several projects as needed. The writers author source in DITA XML and use the DITA Open Toolkit to produce PDFs and online help for distribution.
Problems Faced
The documentation team faced the following issues:
- Large and complex product supported on numerous platforms
- Long-term resource limitations
- Fragmented information as a result of legacy content being converted to DITA XML topics
- Long-standing, formal customer complaints from both internal and external users about accuracy and relevance of product documentation
- Documenting new features and product enhancements consumed all available documentation resources
Progress
Rolling in the efforts to improve legacy content proved much more challenging in this environment due to the complexity of the product and the number of new features added for each release.
The documentation team agreed to initially target the installation guides for improvements to illustrate the value of rewriting and organizing content to reflect user tasks and to minimize confusion. This was an informal effort that served as an inter-departmental pilot project. We worked with support and service personnel to understand the issues and then improve the installation guides. These improvements were made over a period of approximately twelve months and two release cycles and were well received by both internal users and management.
The Pilot Project
After the documentation team demonstrated some success with improvements to the installation guides, we proposed a formal pilot project as part of an overall product management effort to make our product easier to use.
To identify the topic for the pilot project, we polled product management, support, services, and pre-sales personnel to understand which product feature was causing our customers the most confusion and could also benefit most from updated documentation.
Challenges
As the only writer on the pilot project, I faced the following challenges:
Product feature chosen for pilot project not widely understood
Solution: Identified expert-level users from various departments by researching community content to find the most active contributors and interviewing those individuals. For the chosen feature, no formal training was available. When first starting out with this company, I attended overall product training, but the information presented for the pilot project feature was minimal and lacked detail. So, I had to start this pilot project by finding subject matter experts who understood the breadth and depth of the chosen feature and had actually implemented each available option. All of these experts were remote and so I emailed questions to them as I learned to implement all facets of the feature on my own. By the end of this process, I had identified three experts from three different departments (pre-sales, services, and technical marketing) who could verify my findings and also assist with planning.
Effort must be completed in three months
Solution: Devoted a great deal of time to initial research and planning. Doing so was the only way to accurately scope the writing effort. Because I took the time to learn the feature first, planning the standalone document to be delivered and outlining the content for that document took less than a week. Overall, I spent a month of the allotted time on research and planning. Plus, the informal team working with me provided valuable input about specific pain points for customers and also provided feedback about my ideas for the new documentation.
Conflicting information from various sources
Solution: Relied on experts from the informal team to help me weed out the outdated and inaccurate information. But, the most interesting aspect of this particular challenge was that I experienced, first hand, some of the same confusion that our customers complained of. The information in the product documentation did not match the information posted to our community site, and often the articles posted to our community site directly contradicted one another. Plus, there was no resource that explained how each of our product components played a role in the functionality so that users could understand the processing that was taking place and the data that was available to them. This experience caused me to ask many of the same questions posed by our customers. I was then able to organize and present information in a way that made the product feature easier to use.
Lengthy procedures due to product complexity
Solution: Used a tiered approach for procedures, instructing users how to create simple, basic, and then more complex objects. The idea here was to enable users to choose the level of complexity that they needed for the objects that they built. This approach ensured that the product management team continued to fully support our efforts, while enabling us to explore and describe all product complexities in the new documentation.
Results
Because our pilot project was part of an overall product management effort to make our product easier to use, the resulting user assistance received a great deal of attention throughout the organization. Most importantly, the product management team approved of the results and agreed that the entirety of the product documentation should be developed in the same manner and to the same level of quality. As a result, management gave us authorization to reorganize and rewrite seventy-five percent of the product documentation during a release cycle for a major revision of the product. And, we had both formal and informal input and assistance from across departments in the planning and development phases of the new documentation.
References
- Hackos, JoAnn T. Managing Your Documentation Projects. John Wiley & Sons, 1994.
- Hackos, JoAnn T. and Stevens, Dawn M. Standards for Online Communication. John Wiley & Sons, 1997.
- Horn, Robert E. Developing Procedures, Policies and Documentation Using the Information Mapping Method. Information Mapping Inc., 1980.
This article was originally published the Proceedings for the Society for Technical Communications 2010 Conference.
Ann has worked as a technical writer for nineteen years in various industries, including enterprise software, and semiconductors. Ann graduated from the University of Texas Pan American with a master's degree in English and is currently employed by Lombardi, an IBM Company. She has been formally recognized by several of her employers for her contributions and commitment to product quality and usability.
Ann Lette
Senior Technical Writer
Lombardi, an IBM Company
4516 Seton Center Pkwy Suite 250
Austin, Texas 78759 USA
512-203-6225
