Technical Writing, Documentation, and Training

404-873-4288

Our Blog

Expert tips, advice, opinions, and viewpoints.

Single sourcing, according to the ubiquitous Wikipedia, is a “content management method which allows the same source content to be used across different forms of media and more than one time.” (http://en.wikipedia.org/wiki/Single_source_publishing). The benefits are obvious: the maintenance and editing of the source content have only to be done in one place at one time, thus making the editing process more efficient (quicker) and less prone to error. Most technical writers have become single source evangelists because we don’t want to spend our time editing the same piece of content in exactly the same way in several different places. It’s boring, it’s inefficient, and it’s expensive. Root canal surgery (with the right anesthesia) would be preferable.

Here’s how we helped one of our clients see the light on single sourcing.

A few years ago, this client asked us to write a user guide for a new enterprise reporting tool it was preparing to release. During our initial discussions, when we traditionally ask about how the information in the user guide would be used and distributed, the product manager insisted that we use Word to write the user guide so he could deliver the user guide as a pdf file. He insisted the pdf file would be sufficient to meet his customers’ needs despite our many pleadings and arguments to the contrary.

As we began working on the project, however, we discovered that there were different levels of access in the product – admin, supervisor, clerk – that determined the type of information displayed. The clerk could see information related to his location; the supervisor could see an aggregate of many locations, and the admin could see everything the clerk and supervisor saw as well as certain administration functions (like adding users) that were specific to that function. What this meant is that we had to repeat the basic information three times in the document because the client wanted to make sure the clerk (who would only get a “clerk” document) could only see information for that particular level of access; the supervisor the documentation the clerk was seeing plus the aggregated location information; and the admin, all of this in addition to the administrative functions he could perform. What a nightmare!

Every time the application was enhanced – twice a year, if I remember correctly – we had to make the same change in all three locations in the document – clerk, supervisor, and admin. Then we had to review each change to verify that there were no errors, and then the client had to review all three revisions before we could “publish” the revised document. The costs – both in time and money – were outrageous. We began looking for a good endodontist.

We proposed importing the content into our tool of choice (Flare) with the assurance that the client would see his return on investment of this setup charge within a year. At about the same time we were lobbying the client to help us avoid costly and unneeded root canals, many of his customers began asking for a white labeled version of the guide so they could provide the tool to their customers without “advertising” that they themselves weren’t actually supplying the data. To accommodate this request in Word, we had to create yet another file with mostly the same information and maintain both of them – one branded with our client’s logo and one white labeled. Every few months, when the application was enhanced, we had to implement the change in each file (often in 3 different places), review each instance to make sure we got the enhancement right, and deliver two separate files for distribution.

You get the picture. It’s not a pretty one. Finally, with much prodding and begging, the client is willing to entertain a solution that reduces turnaround time and costs – a single source for the content.

Happy ending: the client relents and agrees to let us do the project right. In fact, there’s a nice twist to the story: once the content is in Flare, we can easily convince the client that he could have – at no additional charge – an HTML version of the content to post on the website. The client is happy because he’s saving money on each revision AND getting an online version of the documentation, the client’s customers are happy because they no longer have wade through a PDF file to find the answer to their questions, and we’re happy because we’re spending less time at the dentist office.

Single sourcing may not necessarily be the right solution for every documentation project but it is a very sound and efficient way to keep documentation up-to-date and error free and maintain a modicum of sanity in your technical writers.

View More Posts by: jeffrey

Leave a Reply