Re: on custom-built documents & feature databases...

[Tim Altom <taltom -at- IQUEST -dot- NET>]

At 09:57 AM 3/15/96 -0500, you wrote:
>As much as I am enjoying this s/he tirade... (Even though
>I am not sure why it comes up in user documentation - we
>don't write in the third person any more, do we?)

>I am currently exploring futures for our documentation
>suite. We have several thousand pages which are constantly
>and selectively affected by the introduction of new
>development "features" to the product. Our customers don't
>shop on a per "feature" package. Instead they, procure sets
>of features. Some features will always be purchased together.
>We need the ability to provide any feature permutation.

>The problem: how will we selectively compile their
>documentation to match their feature sets? how can
>we set up feature databases with user-oriented info
>(not functional specification) that serves both
>product information and training needs?

>Is anybody out there currently working on this problem?
>Do you (does he/she/them) care to discuss your (his/hers/
>their) solution in this forum? Moving forward is part of
>the solution but retrofitting it to existing pages is
>another...

There are several answers to your problem, but they all require a boatload
of expertise.

One approach is SGML, where you'll store all of your documentation in chunks
and extract them on demand to form a manual that's specific to the
features/modules that a user buys. This approach requires you to revamp all
of your approaches to documentation, as well as recasting all of your legacy
material into the same format. Then, you'll need to retrain your people and
have lots of computing space available. Good in theory, but hard to implement.

Another approach is something like FrameMaker's conditional text (or, to be
straightforward, FrameMaker's conditional text). It lets you produce several
manuals out of one master document. We've done this for clients. It requires
retooling also, as well as possibly recasting all of your legacy materials.
And it requires a more sophisticated approach, since you'll have to keep
track of revisions differently. It will also require a sophisticated
FrameMaker template and people who are trained to use it. This differs from
SGML in that an SGML database doesn't store formats, only raw text. The
stuff has to be tagged for formatting when it's created and then actually
formatted during the retrieval process, just as HTML is. In Frame, the
material is always formatted and always available, but it can bottleneck
since FrameMaker is the only way out for the data. In SGML, any parser can
extract and compile the data.

The cheapest solution is to make a single manual that covers everything, and
the user can then read only what he needs to know. That has the advantage of
being much cheaper to produce and maintain, at least in labor terms, but
also having the drawback of being infinitely harder on the user and more
expensive to print, since you'll be producing lots of paper that has no
meaning.

Bottom line is...cost and your perception of user needs. If your features
are legion, perhaps numbering in the hundreds, then perhaps you should bite
the big high-caliber bullet and go SGML, so you can mix and match in
thousands of permutations. If there are only a dozen or two dozen features,
then FrameMaker's approach works out very well. In fact, in FrameMaker, you
can do many documents and then print only a select few into a "book" by
selecting which documents you want brought together. The package will then
renumber and recompile the TOC and the index, and update all
cross-references, figures and other progressive items. But it's a nightmare
if you have more than a few dozen "chapters" that you might want to
incorporate. Management time then becomes a big factor.

Further questions answered happily.

Tim Altom
Vice President
Simply Written, Inc.
317.899.5882 (voice)
317.899.5987 (fax)
http://www.iquest.net/simply/simplywritten