Re: Online Doc but no paper

[mpriestley -at- VNET -dot- IBM -dot- COM]

Cathy McNair writes:

>online help. I think an ideal solution would be to produce one source
>document that would be usable online (that is, that is context-sensitive,
>that allows full text searching, that contains hyperlinks, that is chunked
>for effective reading online, and so on) but could also be printed out and
>distributed on paper (with page numbers, a table of contents, an index)
>should the customer want that. The Windows online help does not support

This is supported to some extent in OS/2 with IPF: you can print an entire
document through the help system.  This may not be incredibly useful, however,
if most of your help is contextual (eg "Select Cancel to discard your changes
and close the window." "Select OK to save your changes and continue to the
next window" ... ).

Of course, there can (and should) be more to the help system than contextual
help, and there can be online information that isn't part of the help system
at all.  Our solution was: keep the contextual help in one file, that links
to a separate online document for more in-depth or general information:
a complete online User's Guide.  The information in the User's Guide is
maintained in single-source for both postscript and online (format one way
for online, format another way for postscript).  So: if you want online, you
look at the online version.  If you want hardcopy, you can print from the
postscript version (or just buy the version of the product that comes with
hardcopy docs).

>printing the entire thing as a book. I know Adobe Acrobat claims it can do
>that, but some people on the list have complained it doesn't really live up
>to that promise. I've also heard that you can use SGML files with certain
>applications to create an effective electronic document. Does anyone have
>experience doing that?

We used BookMaster and IPF, which have some similarities to SGML (BookMaster
is a Generalized Markup Language, and IPF is similar).  We may very well be
moving to SGML in the future.  It would make some aspects of the singlesourcing
much easier (by abstracting some of the conditional processing directives into
a higher-level description of formatting differences, ie the FOSI - File Output
Specification something).  It also seems like it would be a great way to
to plan and enforce consistency, both within a document and between documents.
This is also my main reservation about it: when control of document appearance
is centralized, then the writer has much less flexibility in terms of
consistency/quality tradeoffs.  Note: I'm all in favour of consistency
_guidelines_ - I just get a bad feeling about making those guidelines a
built-in restriction of the formatting software.  I think it was Bill Horton
who said something like: if you're following the guidelines more than 80% of
the time, it's probably at the expense of your document quality.

BTW (plug), I'll be presenting a paper at SIGDOC 95 on our experiences with
these issues (single-sourcing online and hardcopy, with multiple writers and
multiple sites).

Take care,


Michael Priestley
mpriestley -at- vnet -dot- ibm -dot- com
Information Development
VisualAge C++ for OS/2
Disclaimer: speaking on my own behalf, not IBM's.