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: 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
want
> to be able to reuse parts of documents, thus saving time & money on
storage,
> 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
we
> 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
together.
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
recipe.
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
Web: http://www.omnimark.com
