One Source -- Multiple Deployment

[Kelly Anderson <kellya -at- VIEWSOFT -dot- COM>]

Hello,

        Although I'm brand new to the list, I've searched the archives and haven't
found this issue addressed directly. If my search wasn't thorough enough, I
apologize for that. It is not my intention to begin a tools war with this
posting, but I want to share what I've learned so far about Single Source
-- Multi Deployment of technical documentation.

        What I mean by Single Source -- Multi Deployment is maintaining any one
specific document in only one tool/format, and being able to use the
contents of this document to create F1 Help, printed documentation and
Online HTML. I would prefer to have the F1 help use MS HTML-Help. The F1
help should be of the highest quality possible (although it needn't use
every bell and whistle of F1 help). The printed manual doesn't have to be
particularly attractive and would contain a proper subset of the
information available in the F1 help. The online HTML should be pretty
similar in appearance and quality to the F1 help.

        This does not imply that all documentation must be done in the same tool.
For example, some documentation could be stored in a database and generated
while other docs could have their primary source in a FrameMaker or
RoboHELP file. Any other primary format would also be ok, as long as the
goals are met.

Why is this important?
----------------------

        I work in a small organization. At the moment, I'm the only excuse for a
technical writer here. (I'm sure most of you are overworked as well.) I
don't have time to endlessly hand convert from one format to another as my
predecessor did. Time after time I've read studies and had feedback from
customers that printed manuals are important. I'll begrudgingly take that
as a given. They'll read the book at home or wherever. I believe that most
of my users (developers) will use online documentation when they are
actually trying to figure something out. Most likely, they will prefer F1
help to browsing the Internet, if the information they need is available in
the F1 help.

        Because documentation often lags development, updating documentation via
the Internet is very important for getting the customers the needed
information. I've been told HTML-Help has methods for this, but I haven't
seen any specifics yet.

So, what tools exist to do this kind of thing?
----------------------------------------------

        I've found a few potential tools. My primary question to the group
involves the trade-offs between these approaches.

        The first path is to use FrameMaker 5.5 to produce the printed manual as
the primary document. You could then use Harlequin WebMaker (or equivalent)
to convert the Frame documents to HTML. (I'm not sure about the robustness
of Frame's own conversion filters, but they don't look as good as WebMaker
on the surface.) You could then use RoboHTML to import and organize the
HTML documents into an MS HTML-Help file.

        The second general approach is to use an F1 help authoring tool that
claims to also support printed documentation. Usually, this is accomplished
through integration with MS Word.

        RoboHELP is a front runner in this category. HTML-Help is generated
directly by RoboHELP. They also claim to be able to produce "professional"
printed documentation. This would be through using MS Word as the printing
mechanism.

        RoboHTML promises to ship an "enterprise" version supporting printing in
Q4 of '97. :-) It's still vaporware.

        SolutionSoft's HelpBreeze (http://www.solutionsoft.com) is another Word
add-on. It looks reasonably nice.

        Olsen Software seems to have another similar product
(http://www.olsonsoft.com) called Hypertext Studio. It doesn't look
particularly astounding, but that might simply be a function of the web site.

        Help Magician (http://www.sinterphase.com) looks similar, although it is
in the late vaporware stage.

       Wextech's Doc-to-Help 3.0 (http://www.wextech.com) appears to be
another reasonable entry into the vaporware category. It actually looks ok,
but being vaporware...

        Again, all of these follow the second major approach which is to focus on
online help primarily, with printed manuals somewhere in second place. (At
least compared to FrameMaker.)

        If anyone has another alternative, I'm listening.

Things I think I'm aware of:
----------------------------

* Most of you would probably agree that Frame is more industrial strength
than MS Word when it comes to creating a printed manual. So in a perfect
world, Frame would be the primary tool/format of choice for the printed
manuals.

* The best tool I know for creating HTML Help is probably RoboHTML,
followed closely by RoboHELP. I don't know about the other products, so it
is possible that they are better.

* Getting WebMaker to always automatically convert Frame files perfectly
involves a complex process of getting the Frame master pages exactly right.
The conversion rules will also have to be tweaked with. This could
potentially take a big up front investment. In addition, Frame would have
to be used with care. The "FrameMaker to HTML" book does explain the
process to some extent.

* From a theoretical point of view, it is easier to take information away
than add it during a conversion process. I would suppose that a FrameMaker
document could have more information than an Online help document.
Therefore, from a purely theoretical standpoint, starting with Frame seems
like the better way to go.

Conclusions and Areas of further research
-----------------------------------------

Right now, not knowing a whole lot, I'm leaning towards the RoboHELP
approach. It at least promises most of what I'm looking for. If anyone has
used RoboHELP to produce printed documentation, I'd really like to hear
about the experience. I already have a fair idea about how good Word would
be for this exercise.

If anyone is aware of a tool that could convert Frame books directly to
HTML-Help, that would likely be the best overall approach, if it worked. I
hope someone out there is working on such a tool.

Thanks for reading this admittedly lengthy e-mail.

-Kelly
"I'm not really a technical writer, I just play one at work."