Re: Single source ducumentation and Doc2Help

[Tim Altom <taltom -at- SIMPLYWRITTEN -dot- COM>]

I think it's vital to repeat that successful single source has little to do
with tools, aside from efficiencies. The key to single source is
unimpeachable structure and predictability. Some tools are more helpful
promoting these than others are, but they remain the foundation stones.
Without good structure, single source is just another name for "doing two
things badly just as quickly as one".

And before someone asks, good structure means that in identical
circumstances, you use identical structure. And the structure should be
compartmentalized, which is a foreign concept to many techdoc'ers. This
means that you don't use narrative style, with transitions and lots of
buildup from para to para. Narrative is fine for print alone, although it's
not the best thing for reusability in print, either. Narrative falls apart
when porting to anything hypertext, unless you want to make an entire set of
paragraphs (like a whole chapter) into one topic/page.

Single source is a compromise, a wormhole between different universes. It's
optimized for neither print nor hypertext. To satisfy the basic needs of
both, systems like our own Clustar Method offer ready-built sets of
compromises. You can either pick an established set, or build your own. But
it's those compromises, along with rigid structure, that makes successful
single source possible. Tool-centrism invites disaster because it pretends
that you can just write something once and let the tool do the rest. That
doesn't work very well.

Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar Method(TM)
"Better communication is a service to mankind."
317.562.9298
http://www.simplywritten.com


Personally, I would not suggest Doc2Help. It is not stable and tends to
>corrupt files. RoboHelp does a _much_ better job in terms of time and ease
>of use.


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=