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.
Subject:Re: Adventures of the SGML Kind From:Mark Baker <mbaker -at- OMNIMARK -dot- COM> Date:Fri, 22 May 1998 14:55:53 -0400
Tony G. Rocco wrote:
>My tech writing department is considering adopting SGML for single-sourcing
>our print and online documentation. This includes 400+ page manuals, quick
>reference materials, and online help.
>Would anyone care to mention anything related to using SGML that would help
>us get a fix on its pros and cons?
SGML is not a complete solution to any problem -- it is just a standard for
specifying markup languages. Many people fall into the trap of supposing
that, because SGML can be used as part of a single-sourcing solution,
switching to SGML -- any SGML -- will give you effective single sourcing. It
You need to think of your problem in broader terms if you are going to be
successful. If you are going to use information in more than one information
product, whether that means different product lines, different audiences, or
different media, you need to make sure that your information has enough
structure to allow it to be used in all these different ways, and that you
have tools capable of translating it from the structure of your single
source into the structures of each of your target outputs.
In order to achieve this, you will have to come up with a structure for your
single source that encompasses all of the structural elements needed to
build each of your target structures. This in turn means that the more
diverse your target structures are, the more abstract from all of them your
source structure must be.
Single sourcing can only be successful if you build a single source with
sufficient structure, at the proper level of abstraction, to serve all the
delivery needs you can reasonably anticipate. So, you need to think about
structure and figure out what kind of structure you need.
Once you have figured that out, you are ready to decide how to express that
structure. Simple structures can be represented in Word or Frame using
styles or conditional text. More complex structures can be modeled in a well
designed SGML-based tagging language (not just any old SGML). Still more
complex structures can be modeled in a relational database or in a
combination of relational database modeling and SGML (what we at OmniMark
call Microdocument Architecture(TM)).
Choose the form that gives you the amount of structure you need, neither
more nor less. Then make sure there are tools available that you can use to
process your chosen source structure into your chosen destination structures
(hint: check out OmniMark). Understand that this necessarily involves some
custom development if you want to have any meaningful control over the
outputs you create.
Finally, beware of SGML consultants who tell you that you can single source
using SGML and then come in and simply model your existing document
structure in SGML. Since this does not give you any more structure than you
had before, it does not make single-sourcing any easier than it was before,
if just leaves you having to buy and learn new tools.
Structure is the key to single sourcing. SGML, properly understood and
applied, is a useful part of the toolkit used to implement the proper
structure, but it is not the answer in itself.
Manager, Corporate Communications
OmniMark Technologies Corporation
1400 Blair Place
Canada, K1J 9B8
Email mbaker -at- omnimark -dot- com