Re: How to write for information reuse?

Subject: Re: How to write for information reuse?
From: "Mark Baker" <mbaker -at- omnimark -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 11 Feb 2000 12:19:13 -0500

Ballenberger Gerd wrote

> We are currently setting up a DMS with FrameMaker+SGML and a Chrystal
> Astoria document database. One of the main reasons for this is that we
> to be able to reuse parts of documents, thus saving time & money on
> maintenance, translation and review of these parts, and improving overall
> documentation consistency.
> So much for the theory. In practice I had one case where a document part
> that I could have reused didn't fit into the target because the heading
> levels didn't match. There are some more obvious things to consider which
> are aware of, but we certainly don't have the broad view to train our
> writers properly.

You have hit on one of the key weaknesses of these systems: they provide no
support for information typing or componentization.

You can only *reliably* reuse something that was designed to be reusable. It
must have well defined characteristics and a well defined interface.

You can't expect to take some parts from a Ford and some parts from a Toyota
and expect to make a working Chevy. The components were not designed to work

You can't take parts from a jigsaw puzzle depicting a house, and one
depicting a lake, and snap them together to make a picture of a house by a
lake. Fragments are not components.

You don't make chicken vegetable soup by taking the chicken from a can of
chicken noodle and the vegetables from a can of vegetable beef. You have to
start with raw ingredients and cook them together according to a specific

You need to develop a type system for your information content and ensure
that all information is created as components that correspond to types in
that type system. This cannot be done by writing documents and then
decomposing them into fragments.

You don't make Lego blocks by hitting a plastic house with a hammer, or even
by cutting it apart with a scalpel.

For serious large scale reuse, you need to explicitly plan to create and use
well defined information components.

While the system you have does not actively prevent you from doing this, it
does nothing to help either. It supports controlled borrowing of document
fragments, but it does not support controlled creation and reuse of
information components. Unless you move to a system which explicitly
supports componentization, you will have to implement strict manual controls
to ensure proper componentization.

Mark Baker
Senior Technical Communicator
OmniMark Technologies Corporation
1400 Blair Place
Ottawa, Ontario
Canada, K1J 9B8
Phone: 613-745-4242
Fax: 613-745-5560
Email mbaker -at- omnimark -dot- com

Previous by Author: Re: Technical Writing Style
Next by Author: Re: content management & documentation management
Previous by Thread: How to write for information reuse?
Next by Thread: RE: How to write for information reuse?

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

Sponsored Ads

Sponsored Ads