TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
David Castro writes:
>Has anyone seen an example of single-sourcing that is *good*? I've
>seen examples (such as the manual for RoboHELP 3.0...the last release
>before RoboHELP 95), but none of them have been *good* documents. I think
>that, in theory, single-sourcing is wonderful, but in execution, its
>inherent problems are pretty obvious.
I agree that I have seen very few, useful documents that are single-sourced. I
strongly agree that we should not take a single document and convert it into an
online form and call it online help. We have to carefully design both our
books and our online help systems, and not lower our standards because we have
the *need* to single-source information. It is a need, a necessity, a reality
that single-sourcing must exist. However, we need to rethink how we
single-source information. Here's one story:
Certain types of information can be single-sourced better than others.
Reference information is the obvious choice, as it is most often discrete
pieces of information and repetitive in nature. I once single-sourced a
programmer's reference manual with online help panels using a single set of
tagged files. We wrote conversion programs to manipulate the tags into the two
different formats for printing and compiling WinHelp files. There was no need
to duplicate this information in different sources. However, we did not create
a hardcopy document and then convert it into a help file. We worked from the
inside out, breaking down the pieces of reference information and then sharing
only those pieces. The hardcopy book had a master file that pulled in the ge
nerated source files, and the online help system had a master file that pulled
in its specific generated source files. You could do this with task-based
information just as easily, but again, you would have to break down your
information into task-based modules that can easily be inserted into a master
file/shell for each of the different environments you are serving.
Single-sourcing information can be very successful if you think from the inside
out, as opposed to converting from one media/format to another.