Single source publishing

Single source publishing, also known as single sourcing, allows the same content to be used in different documents or in various formats.

For example, a software company may have several products with user guides that share a common procedure, like instructions on how to open a file. Rather than maintain duplicate versions of this procedure (one in each manual) the manuals can share the content, perhaps merging it into the document at the time of publication. Eliminating duplicate content can reduce translation costs and maintenance costs, improve consistency and minimize errors.

Single sourcing also allows the creation of documents in various formats from the same content. For example, a company might use the same content in online help, a printed document PDF, a Web page and in an Interactive Voice Response system. With a single source solution, the company only has to update the one source file for the content and regenerate the four outputs.

Ideally, the tools used for single-sourcing do not require human intervention to customize the formatting or content for the various outputs. There are many approaches to single-sourcing. The master information can be stored in any number of ways. These might include word processing documents, databases, XML files, content management systems, GUI builders or spreadsheets. Various tools can then be used to extract the information from the master document and format them into various output formats or modalities.

A number of tools can be used to generate the various modalities from the master document. Programming languages provide the greatest flexibility, but also provide the least amount of direct support. If the master is stored in XML, or a format that can easily be transformed to XML, then XSL and XSLT can be used to transform the document to various forms. Code generators such as CodeSmith or Microsoft's ASP.Net or a graphical stylesheet design tool such as Altova's StyleVision can be used to make transforms more easily than a general purpose programming language. Content management systems may have various output modalities supported directly. A system could be created using a word processor like Microsoft Word, if it has programming support.

At the top end, in both price and functionality, there are programs specifically designed to support single sourcing. These will require less effort to configure and manage than more general purpose tools. If single sourcing is something you want to attack seriously, you would be well advised to investigate these programs carefully. At the very least, they can give you ideas about what sorts of features you would want in your in-house single sourcing solution. There are offerings in this area from Adobe, Quadralay and Omni Systems.

Designing the Master

One of the more difficult parts of single sourcing is designing one or more master formats. To do this, you need to notice if you have a lot of similar things that all need to be documented. For example, menus and dialogs in a GUI program, classes in a programming application programmer interface (API), widgets in a line of similar products, objects in a museum collection, parts of complex machines, and so forth. Once you have identified a set of similar items, what characteristics do each of these items have in common? A computer programmer or analyst skilled at object-oriented programming can be helpful at this stage in identifying and organizing common attributes. Store information about each object and attribute in your master file. How to do this of course varies considerably depending upon the nature of your master file. In choosing the master file format, keep in mind those who will maintain the actual words. Often, it will be primarily technical or professional writers. Choose a tool that they will be familiar with or can learn quickly. Raw XML, for example, might be difficult for many writers to manually input accurately.

Having fine and quantified granularity of your information can be helpful in enabling various methods of massaging the data for different output modalities. For example, you don't want your master file to consist of pages upon pages of unorganized text about the object. You generally want to know such things as its name, a short description, a long description, perhaps how it is used in a given context. For a museum item, for example, you would want its catalog number, the collection it's from, its age, where it was collected from, how it was acquired, its value if known, its use, its provenance, its historical context, etc. With all of these individual pieces of information, you can output cards for use in displays, descriptions for the virtual museum web site, and printed manuals describing specific collections. If you just have pages of unorganized text, this becomes much more difficult to manage from a single source perspective.

If you have a database relating to the objects, study it. There will be many ideas you can get about what might be interesting about the items you are documenting. A database programmer can also be helpful in helping you to design your master files.

There may be multiple dimensions to the master data. For example, you might have the data translated into various languages. Every time you add a dimension, you make maintenance of the master data exponentially more difficult. However, if the problem you are solving warrants multiple dimensions, then it's also likely a good candidate for single sourcing.

The Transforms

Once you have identified these objects and attributes, think about how they will be presented in each output modality. Do mock ups of your data for several objects in each modality you are thinking about supporting. If you can translate the data by hand from your master format to each output modality with the control you are interested in having, then you're on the way to a successful system. If you demand ultimate control in one modality, you might consider that modality as your master, or part of your master. For example, if a printed manual is the most important modality, you might consider FrameMaker as your master format since many technical writers are familiar with it, and it has tags that are easily transformed into other modalities using the single source tools mentioned above. You might also keep in mind that translations to other languages are often outsourced, so a common format that can be easily used by translators may also be important.

Whatever master format you choose, you should provide templates for each type of object you wish to document. This helps maintain consistency over a collection of master objects. It is advisable to design your master format very carefully before beginning to use it. Going through all of your master objects making changes to conform to a change you think of later can be very expensive, tedious and error prone. Planning and thinking are very important to this process.

Single sourcing can be accomplished successfully in many contexts where you have a large number of similar items to document. It requires considerable up front planning and careful training of staff inputting the master data. Alternatively, effort can be put into creating a program or template for inputting the raw data in a prompted way so that training can be minimized. Balancing these efforts in the context of maximizing your productivity is not a trivial task, but given a project of reasonable size, it can give great returns in flexibility and maintainability over.

External links

* [http://www.stcsig.org/ss Society for Technical Communication Single-sourcing Special Interest Group]
* [http://www.agilemodeling.com/essays/singleSourceInformation.htm Single Sourcing Information - An Agile Practice for Effective Documentation]