Re: object-oriented documentation

Subject: Re: object-oriented documentation
From: "Tim Altom" <taltom -at- simplywritten -dot- com>
To: "TechDoc List" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 14 Dec 1999 10:49:08 -0500

Mark, what you're describing is true; for a full-bore "component based
information" system, there's little that suits the bill.

The term that's looming on the horizon for this is "single source", which
started out meaning "write once, use it intact somewhere else" but has
become extended to what you're describing as component based, with granular
parts that can be served in infinite combination.

What we've found here is that many companies don't start literally at the
front end, constructing a structure for their documentation. What they often
do is take the "river raft" style they've always used, construct a
hellaciously complicated and unfriendly DTD for it, then try to reuse these
unrelated chunks. That doesn't work well, to be charitable.

That's why we came up with the Clustar Method, which addresses that exact
problem. Using the method for task-oriented documentation is a huge savings,
especially if the client wants to hold the door open for eventual XML/SGML
distribution. We're working on an XML DTD for Clustar right now, and we're
astonished at how simple the darned thing is, even when we build in all the
little granular things like beginning and ending of bulleted lists.

This lack of up-front structure is, in our experience, as much of a barrier
to component reuse as is the lack of good component management tools. No
tool can reconcile all those chunks that just don't fit into the schema,
because some writer or editor took off on a tangent and didn't follow a
pre-defined structure.

Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar Method(TM)
"Better communication is a service to mankind."

> Back in 1995, I coined the term "Component Based Information Development"
> describe this process. (See the Proceedings of SGML 96 for a paper
> describing the basic idea.)

Previous by Author: Mastering Framemaker 5 update
Next by Author: Fw: Baseline Skillset for Technical Writers?
Previous by Thread: Re: object-oriented documentation
Next by Thread: RE: object-oriented documentation

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

Sponsored Ads

Sponsored Ads