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.
The keys to single source are planning, discipline, and a willingness to
forgo the ideal for the doable. Essentially, single source works if you're
willing to turn your documentation efforts into a kind of assembly line,
with complete adherence to standards and "fit" in all your parts. The tools
are important, but they aren't the bedrock.
The first thing to tackle is a repeatable structure. By "repeatable" I mean
predictable, set up in advance, and adhered to by all who participate in the
enterprise. No exceptions. Just as one out-of-tolerance part on an assembly
line can cause widespread calamity, one file in an unapproved structure can
seriously disrupt your process.
The structure should ideally be hierarchical. That is, it should be built
like a tree, with a root, branches, and leaves. XML is as good as it gets.
Now, when you've created your content, and it's in a particular structure,
you store that and wait until you need a document. Then you apply
formatting. You can also store the pieces and assemble them in different
patterns, too, but that's a bit complicated.
One of the rubs of single source is that you'll probably end up having to
make structural compromises. For example, a document designed expressly and
totally to be a "Dummies book" isn't going to make a good help file. Your
structure and creation must take into account the compromises that must
exist between the various formats. That's where our Clustar System comes in,
having ready-made structure that's a good compromise. Other systems make
compromises elsewhere, but all systems must make them. If you find yourself
constantly hand-tweaking the HTML, WinHelp, or other outputs, then you're
missing the major benefit of single source.
At the far reaches of single source is fully valid XML/SGML, which lets you
break any document into component parts that are separately stored. Any
document is then created "on the fly", possibly without ever having existed
before. For example, a given maintenance document may have only installation
steps for five out of ten products, because a given customer has requested
only those procedures.
Single source is a marvelous thing for those who are temperamentally and
culturally capable of working within it. Not every writer or company is.
Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar(TM) System
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info http://www.simplywritten.com
seriously considering implementing single-sourcing
> throughout the company... everyone is excited about the possibilities the
> approach offers and the real benefits we information developers bring to
the
> company under such an approach. Another obvious advantage is that we could
> leverage the fact that our company is fairly young to establish the system
> and processes as part of our culture without requiring extensive re-work.>
>
