Single-sourcing: an ever-moving target
For many years, "single-sourcing" has held an important place in the technical author's vocabulary. This article examines how the meaning of this term has evolved and continues to evolve as technology progresses and authors face new challenges.
Many platforms, many versions
If you compare the IT world of ten years ago with the situation five years ago, one of the most obvious changes is the number of established hardware and software platforms that suffered declining popularity, sometimes disappearing without a trace. At the same time, other platforms rose spectacularly to become the new market leaders. During this period, mainframes and minicomputers surrendered centre stage to personal computers and workstations. The battle between Microsoft and Apple reached its height then died away as Windows dominated the desktop. OS/2, NeXTSTEP, and various other operating systems stirred up some initial enthusiasm but never made the grade. And Unix continued to acquire new features without ever really winning the confidence of the business world.
One problem for software developers during the period was that the market often required an application to run under several operating systems. In some cases, supporting a particular platform was unprofitable but necessary for political or marketing reasons. When developers produced software versions for different platforms, the resulting products always varied to some degree. Even if the different versions provided essentially the same functions and features, each version looked different because the owner of each operating system advocated different user-interface standards. Rather than coding from scratch for each application version, programmers adopted tools and work strategies that let them reuse system designs and existing code.
In their own way, technical authors faced similar problems. They had to produce a slightly different set of manuals for each version of an application even though much of the information was identical in each set. Fortunately, software for technical publishing helps authors overcome this problem with features such as "conditional text". Let me give you an example. Imagine that you have a file containing information about an application that comes in two versions, one for Windows and one for Macintosh. In this file, certain sections of text only apply to the Windows version, some only apply to the Macintosh version, and some sections are equally applicable to both versions. If you use publication software that supports conditional text, you can enclose all your Windows-specific information with tags, which you might choose to name "win". Similarly, you can enclose all your Macintosh-specific information with tags named "mac". Then, if you want to print a Windows-only version of your file, the publication software lets you hide all the "mac" sections. As well as printing your "win" information, the software also prints all the text that you did not enclose in conditional tags.
This is how technical authors originally understood the term single-sourcing—using one information source to produce several printed documents, each with a different content. Compared to ten years ago, there is probably less demand for different manual versions for multiple operating systems. However, many authors still use single-sourcing in the original sense. For example, they might need to produce different manuals for standard, lightweight, and customised versions of an application. However, other forms of single-sourcing have come along.
Help, here comes another medium!
Even before graphical user interfaces became widely adopted, some applications offered users simple forms of online help. However, it was the overwhelming popularity of Windows that brought online help into widespread use. Microsoft offered free, basic tools for authors to create help for Windows applications, and other software companies developed more advanced, author-friendly help-authoring tools (HATs).
Although most software companies began to integrate help into their applications, many continued to provide printed documentation as well. This trend brought about a new set of issues for technical authors. In most cases, software users needed much the same information, whether it was provided through online help or on paper. However, authors needed to present their information in two different ways because online help and paper are rather different publishing media. For example, the low resolution of monitors makes on-screen text less legible than printed text. Authors must consider this difference when selecting font faces and sizes for help. As well as imposing constraints, online help also offers new possibilities for assisting users; for example, help can include hypertext links and search functionality.
Initially, if authors wanted to produce both paper documentation and online help, they had to develop the content for one medium and then carry out a time-consuming transformation process to make the content suitable for the other medium. To be more productive, authors needed some kind of single-sourcing solution, and fortunately most of the HAT companies enhanced their tools to meet this demand. When working with a suitable HAT, an author could change between publishing a manual or online help almost at the click of a button. However, the tools themselves were only part of the solution. Authors found that single-sourcing worked better if they designed and wrote their content so that it was more geared to the demands of the help medium. For example, they structured text into smaller chunks and to wrote more concisely than they had previously.
Over subsequent years, the Windows help format acquired a few more features without changing dramatically. Many software publishers began to reduce the amount of paper documentation they published, leaving users to rely more on the online help. As a consequence, some technical authors stopped producing printed documentation and concentrated exclusively on producing help. For these authors, single-sourcing became less important or unnecessary. Then the Internet, and particularly the World Wide Web, became a global phenomenon and changed everything.
The Web and HTML everywhere
The features of early web sites—before all those flashing adverts came along—were similar to online help. Originally, sites were just sets of online documents, joined by hyperlinks, that presented text and graphics in simple layouts. It is no surprise, therefore, that technology companies should consider using web browsers and HTML as the basis for a new generation of help systems.
Unfortunately, HTML-based formats for online help became a minor battle in the browser war between Microsoft and Netscape. First Netscape introduced NetHelp. Then Microsoft riposted with its compiled HTML Help format. Other major corporations felt compelled to join in. Sun announced the arrival of JavaHelp, Oracle proposed Oracle Help, and there were rumours that yet other competing formats would join the fray. So some authors found that they now had to publish information in several help formats and sometimes as hardcopy as well.
Fortunately, as new help formats arrived, the HAT development companies responded. They extended their products so that technical authors could publish the new help formats from the same source files they had used to produce printed documentation and the original Windows help format. At least that was the theory. In practice, single-sourcing was actually more complicated because each help format supported different features (and some of the HAT producers concocted their own new help formats as well).
As well as influencing the evolution of online help, the spread of the Web has affected the work of technical authors in other ways. They often need to publish information as printed documents and in formats suitable for display on the Web (usually as HTML or Acrobat files). Once again, the vendors of publishing tools rose to meet this new challenge by adding more output options to their products. For example, with a combination of Adobe Framemaker and Quadralay WebWorks Publisher, authors can take a single source file and publish it on paper, as an Acrobat file, in various versions of HTML, as XML, or in any of the most popular help formats.
Every publication format has its own special features so developing content suitable for several formats can be complex work. Tool vendors like to claim that their software makes single-source publishing easy and efficient. But this is only true when development is preceded by careful planning and if authors create their content with care. For technical authors, the future will undoubtably bring new challenges. It will be interesting to see whether the concept of single-sourcing can continue to evolve to help us address the new issues we shall face.
Copyright © 2003 Stephen P. Reynolds. All rights reserved.
|