Re: How to write for information reuse?

["Tim Altom" <taltom -at- simplywritten -dot- com>]

You've just rediscovered the first principle of single source/reuse: If it
isn't structured and designed to fit, it won't fit. The situation is like an
existing product that needs a bolt-on addition. If the bolt hole pattern
doesn't match, nothing will make them match. At best, you can create some
kind of adapter, but that's not going to work for production.

The same is true of existing documentation when you decide to reuse it in
pieces. The chances that traditional "river-current" legacy documentation
will match anything you do today are somewhere south of zero. There's no
structural match. At best, you may have heading tag mismatches, with sound
structure. At worst, the document hierarchy doesn't match. This is why many
organizations want to move to XML or SGML, so there's some kind of
monitoring system to check structure. That's the key...formatting is not a
problem, nor is content.

There are three things you can do: First, you can give up. That saves you
aggravation, but it perpetuates the inefficiencies you complain of. Second,
you can analyze all your old legacy documentation to discern structures,
then go to a truly structured environment with a strong Frame template,
SGML, or XML. You can define a DTD that encompasses all the decisions other
people made in the past and left for you in the documentation. This approach
is approximately as much fun as bailing the Titanic out by yourself, and is
only a little more expensive than replacing the ship. No kidding...it's a
huge amount of work, and it never really stops.

Third, you can ditch the older structures and move to a structured
environment that's new and controllable. That's when you want an
out-of-the-box solution like our Clustar, or design such a system for
yourself. Ideally, you then have:

* A structured methodology;
* Predefined Frame templates with appropriate tags;
* Training in how to apply all of this.

But the bottom line is that you must somehow either reconcile all the old
mismatched structures or you must move on to a truly structured environment.
Otherwise, the bolt holes will never line up and you'll spend horrendous
amounts of time creating adapters for yourself.

Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar Method(TM)
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info
http://www.simplywritten.com



> What are the Do's and Dont's of writing information that should be
reuseable
> in a databased Document Management System?
>
> 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.
>
> Can anyone share some experience, or point us to appropriate sources?
>
> (I searched the archives and found some postings, but nothing really
> comprehensive. One poster, Debby Schryer, had asked the same question last
> year and asked for direct replies, but her e-mail address doesn't exist
any
> longer.)
>
> Thanks,
>
> Gerd -dot- Ballenberger -at- med -dot- siemens -dot- de
> Siemens Medical Systems
> Erlangen, Germany