Re: How to manage shared content

Subject: Re: How to manage shared content
From: HALL Bill <bill -dot- hall -at- tenix -dot- com>
To: "'Techwr-l posting'" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 1 Sep 2000 08:13:49 +1000 (EST)

Abby Matsumoto asked how other people manage text that is shared by multiple

It seems to me that when you have 50% of your text shared in common across a
suite of manuals it is time to start considering migrating your work into an
SGML/XML or other structured authoring environment. The shift from "word
processed" or DTP documentation to structured authoring and management isn't
easy. However, for long-lived, highly redundant and frequently changed
document sets, the savings in author time and management effort and the
improvement in quality should cost justify the shift.

Because we are a substantial Defence prime contractor, we have adopted a
high-end system for our needs (RMIT's SIM system -,
which is also supported in the US). Others which would have served our needs
are XyEnterprise's Parlance (, Chrystal's
Astoria ( and possibly BroadVision's BladeRunner
( BladeRunner's database
started its life as Texcel's IM, which was acquired by Interleaf, acquired
in turn by BroadVision. If you follow this up, I would be careful to confirm
that BroadVision will continue to support BladeRunner as a product for the
general documentation management market (as opposed to its E-Commerce uses).
Oracle and Documentum are also providing increasing support for structured
documentation - but these would also have to be considered to be high-end

There are also some comparatively inexpensive SGML/XML databases around,
such as Poet (, but these would require a larger DIY
component to implement. You might also check out Chrystal's Canterbury which
is designed to work in a structured way with normal FrameMaker. Some of the
comments I have heard about Canterbury were not entirely positive - but the
situation may have changed as the product is improved.

An even less expensive option for standard texts used deep within the
document hierarchy is to set them up as text entities (these can also
include SGML tags). In maintenance or technical manuals for military
hardware, it is entirely appropriate to treat standard warnings, cautions
and notes this way. However, this probably wouldn't be appropriate for large
blocks such as chapters and sections that would need to include content that
varied between documents.

If you are good at programming, you might also consider script-based
document assembly processes.
SIM's Ace language is available as a free download
(, and
includes sophisticated SGML/XML/HTML processing libraries. OmniMark (a
powerful proprietary language), and the public domain Perl and Python
languages also all have SGML/XML processing libraries which would help in
such tasks.

Your DTD(s) need to be structured to facilitate the logical reuse of
standard elements.

FrameMaker+SGML is a good tool for many shops, in that it provides for both
authoring and publishing, and would build on already existing FM expertise.

Again, the conversion process from a 'word processing' environment to fully
structured documentation management is not cheap or easy, but the rewards
can be great. We are currently in the process of converting ship maintenance
documentation from structured word processed documents (WordPerfect merge
tables) into SGML. In the WordPerfect environment we 'single sourced' more
than 20 different deliverables from the one set of merge tables - but we
simply could not manage the complexities of ship-specific differences. The
first stage of our conversion process is reducing approximately 8,000
ship-specific maintenance routines for the four ships already delivered to
approximately 1800 routines which will be applicable to a class of 10 ships
belonging to two different navies. This is achieved through implementing
'single source', multi language', 'applicability', and 'effectivity'
concepts in the DTD. The second stage, involving detection and reuse of
similar texts, to be implemented later this year, will reduce the total text
to be managed by at least another 50%. This will reduce our overall
documentation management requirement for the class of 10 ships by 95% to
provide a higher quality of information than we were delivering from the
WordPerfect environment.

Bill Hall
Documentation Systems Specialist
Integrated Logistic Support
Naval Projects and Support
Tenix Defence Systems Pty Ltd.
Williamstown, Vic. 3016 AUSTRALIA
E-mail: bill -dot- hall -at- tenix -dot- com

Previous by Author: RE: Repeating the Same Verb
Next by Author: Thought-provoking web page question: what do you like?
Previous by Thread: OT: RE: informational interview questions
Next by Thread: The world's most frequently read instructions

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads