Skip to Content Skip to Main Navigation

Case Study: Implementing Single Sourcing – How NOT To Do It!

Editor’s Note: This was the feature article in this month’s TechCom Manager newsletter, reprinted here with permission. Click the previous link to subscribe to the newsletter.

Jo Levitt

Jo Levitt, Author of Case Study: Implementing Single Sourcing - How NOT To Do It

I first heard about modular writing and single sourcing while working at a division of Hewlett Packard (HP). As a large company, HP uses the typical change processes and has needs for everything, such as localization and standards. There, we implemented single sourcing using an internal system. When I moved to BigBand Networks to help implement the Author-it system, things were much different, especially due to a fast-paced management team that encouraged change as long as it didn’t cost too much.

In many ways, the two teams were similar with somewhat dissimilar challenges. This case study looks at implementing single sourcing in two rather different ways. The backdrop for this study centered around two teams, each with five-to-seven writers using MS Word and Adobe FrameMaker for authoring. The result: two successful single-sourcing solutions.

As you read through this article, keep in mind the various benefits of single sourcing. For example:

  • Update content one time and automatically populate the information across all documents that share the same information.
  • Major cost savings on translation, increasing significantly as languages are added.
  • Compile new documents more easily from existing database elements.
  • Easier to manage all documents when they are in one place.
  • Simpler online-help-development process.
  • Easier Web content delivery.

As a result of the initiatives discussed in the following cases, both companies, HP and BigBand Networks, are now successfully single sourcing and realizing major benefits.

Case 1 – HP Indigo Division

After a period of considering various types of system and processes at HP, we discovered we were not allowed to purchase external single-sourcing software. Why? HP provided a free, homegrown internal system which we’ll call System X. When you work in a large company, you might not always be aware of certain software you’re “expected” to use. So rule # 1: Before you investigate off-the-shelf software, first determine if your company requires you to use an internal system. Since tools were decided for us, we were limited in our approach to new processes.

For this case, System X consisted of:

  • An off-the-shelf XML editor run locally.
  • An off-the-shelf CMS (Content Management System) database held centrally and accessed by HP staff all over the world.
  • Homegrown System X output tools used to produce PDFs, all types of help files, and different flavors of XML.

An external company converted our first document to XML. Although we imported it into System X, there was a lot of cleanup required. Later, I discovered this is a common issue, but there are some things you can do to reduce the pain. Some suggestions follow.

Things You Can Improve

  • Styles – Most writing teams think they are pretty consistent when using styles. Often, conversion projects uncover the truth. Therefore, review all documents you are converting and make sure they really do use the official styles, especially the older documents. Although you may find similar but different styles amongst different document types, merge what you can.
  • Style mapping – Prior to conversion, examine the mappings from old styles to new styles. After you have a complete list of styles to be mapped, identify the duplicates, which an automated system or a content professional unfamiliar with your documents cannot see.
  • Correct use of structure – Try to get the structure right before the conversion. Doing it afterwards in new unfamiliar software will be no fun! Also, make sure that similar document types are using similar structures. Again, look at older documents which may still be using older standards.

Time-Consuming Issues With Few Shortcuts

  • Resizing images– In Word or FrameMaker, you will usually size images inside the document to fit the page. This is not possible in most XML systems. Images are displayed exactly as they were brought in to the system, which is often too big. However, you may be able to do some batch processing to adjust image sizes. Unfortunately, the only way to be sure this is right is visually check each image that is output.
  • Text in images – In Word or FrameMaker, it is not uncommon for authors to add descriptive text to images by inserting text boxes. Most XML systems do not allow this. If you are localizing your documentation now or in future, now is the time to remove all text inside images. If you cannot manage without text inside images, first consider converting all text to numbered items, then add tables underneath the image to explain what each numbered item refers to.

How much cleanup time can you expect? At HP, it took:

  • Three weeks or so to clean up one help file containing about 400 topics.
  • Several months to bring in all the help files and other documents.
  • Over a year to break up all the material for single sourcing,
  • Another two years before we really did this efficiently.

Many training companies do not teach how to chunk your content or teach which single-sourcing approaches are best for certain scenarios.

We had great difficulties with the localization process until we moved to an internal HP localization service, which understood XML systems and could access our CMS data directly. Suddenly, we removed a whole set of tasks from our delivery process (exporting sections of XML, and sending for translation, importing the translations back into the right place in the CMS, and creating multiple outputs in multiple languages). The Localization Manager did all of this for us.

At HP, we took a slow, cautious approach to implementation and had to retrain five of the seven team members after we finally put all our documents into the system. This caused unnecessary overheads, and, in some cases, the feeling that a writer was “second class,” because he or she was not yet an XML user. It also created more resistance.

Case 2 – BigBand Networks

At BigBand, the single-sourcing and online help requirements were similar and there was a future need to make all the documentation available on the Web. There was, however, no requirement for localization.

The system chosen was Author-it (AIT). Until the change, the PDF output had been produced mostly from FrameMaker, using an add-in which produced very nice PDF effects. We wanted to preserve this style, so our AIT supplier suggested we use a company that could transform output back to FrameMaker through XML.

We ran a short pilot and everything looked good., including some output which looked suitable for external delivery. So during a work lull, we trained the whole team and took the opportunity to import all our documents.

It took time to develop a good import process. By definition, a pilot project cannot cover all scenarios, and we kept finding new issues that we hadn’t thought about initially. The training had not covered importing in depth and this was our first experience with the tool. At HP, we found that paying an external company to import our documents was not expensive. By starting with importing at BigBand, we were able to take some writers off the new system before they really got started. As a result, it took some effort to convince them of the value of outsourcing the importing. Plus, it didn’t help that they had to do some of the same cleanup work that was required at HP.

Unfortunately, the company we used to produce output was very slow to deliver. We now had all our documents in AIT, so we were not willing to make the next set of updates in the old system. We put pressure on the company, but it seemed we would not have output ready in time for our next documentation deadline. We cut our losses and went back to the traditional printed output (Word) which AIT provides. Next, we had to quickly reconfigure AIT to produce Word output the way we wanted it and design a Word template which mimicked our FrameMaker template as closely as possible. We had good support from our Author-it supplier and met our deadlines.

Setbacks and Lessons Learned

When deciding what methods and tools to move to, keep asking questions like, “What haven’t you told us? Try to think through the process you are planning and ask whether it is practical. Ask vendors to describe issues with other implementers. If possible, arrange to see how other companies implemented the suggested solution.

Don’t expect too much from the pilot project. To really know what to expect, you would have to try the system with all your different document types, document sizes, and other factors. You can’t do it all, so assume the pilot will only show you how easy the tool is to use, and possibly help you to adjust your document production process to fit better./p>

Prior to a conversion, clean up as much as possible. For example:

  • Remove text in images.
  • Remove duplicate and unused styles.
  • Remove duplicate and unused conditional text tags.

Whatever system you use, do not expect the new PDF or help to perfectly match what you had before. Any system designed to produce multiple outputs is likely to make compromises in order to match the differing requirements.

During your process implementation, do not use any unknown companies that do not come with strong recommendations. Also, don’t try to force your selected software tools do something they weren’t designed to do unless you have LOTS of extra time.

Expect resistance from some of your writers. Most people have difficulty accepting change, especially if they feel the value of their current skill set is being challenged. It is important to get the whole team involved as early as possible. A long implementation time can cause even more resistance, plus some writers can forget how to use a system during long periods of downtime. Clearly, faster implementation keeps the momentum going.

If startup processes are not sufficiently documented, then document them yourselves. At HP, every time someone upgraded their computer, we were glad to have those procedures in hand. At BigBand, the import procedure became very useful later when we had extra files to import.

Graphics are problematic. If you can find another similar to yours that has already been through the process, ask them for graphic guidelines or if they can give you tips on how they handle graphics.

Localization is much cheaper once you get a good XML system up and running, but the most benefits come from working with a localization company that has real experience with these systems and knows how to control the process. If possible, give the localization company direct access to your database.


In both cases described above, the training did not cover the change in mindset that is required when moving to a single-sourcing system. So, you should encourage your trainers to devote some time to this to better prepare writers for the transition. The training should also cover import processes if you plan to import your current documents yourselves, how to set up document structure, how to “chunk” (break up your documents into objects), and various other single-sourcing processes.

Remember, every system has bugs. Therefore, I recommend adding 20-30% to your implementation time for finding workarounds.

About the Author

Jo Levitt started her working life as a software engineer, moved on to software process improvement consultancy and is now at her career peak as a technical writer! She uses her process improvement background to help writing teams through the change to object-based writing. Look for her on Linkedin at:

Please follow and like us:

Leave a Reply