Re: HTML as document source

[Jan Jackson <jjackson -at- SUSQ -dot- COM>]

<   >Yes, some web pages do look good when printed (on a laser or a good-quality
<   >color jet). The problem, though, as you noted in item 2, arises when the
<   >"page" on the screen runs more than one paper page.

<   The problem is not how to print hard copy from Web pages.  Rather, it's
<   much easier to figure out how to create both hard copy and Web pages from
<   material stored in the same database.

This issue of single sourcing online and paper documentation is not new
with HTML and is more than just a matter of scrolling pages. To have an
effective online or paper document, it has to be designed for that medium.

A manual needs a toc, an index, cross-referencing and an integrated and logical
structure. Hypertext is more a collection of topics which are connected by
well-thought out and accessible links. It has a more limited page size,
poor resolution (compared to paper), and has to work hard to replace the
scoping function that thumbing through a manual serves.

You can fairly easily convert rtf to html or whatever, which works for certain
types of documentation, but not for manuals, per se. Printing out pages from
hypertext is sometimes perfectly appropriate, such as printing out procedures,
but again this is only piecemeal.

I've been researching this issue for a while as I have to maintain manuals
and WinHelp for some packages. Right now I have an intricate system for
updates, etc., but basically, I am maintaining two separate systems at almost
double the work. Enter HTML which is great, but adds an extra burden.

The only two solutions I see for single sourcing are SGML and using a
database as mentioned above. However, and this is a big, they both require
very strict definition and manipulation of information which is not
trivial. Further, they both require programming to take the tagged info.
and generate code for the destination package. I've been too overwhelmed
with work to sit down and really prototype this, but I can see that these
are both programming solutions and would require much time and effort.
Companies with high-volume documentation generally hire a team of consultants
to work out such a process. Other companies just come out with crappy
documentation for one or the other medium or do double the work to
produce decent docs.

To the original poster (sorry I've lost the thread), you are absolutely
dead right about feeling uncomfortable with the procedure. Because you
lose either way. Either you maintain the two systems or you lose control
which will eventually lead to a crisis in document integrity. I think
that one great advantage is that the developers are willing to put the
time in to check the information. I personally would suggest that they
make changes to a copy of the html and submit a copy of the original
and changes to you so that you can update the manual, edit the html,
and reorganize if necessary. Someone has to be in charge.

I would, BTW, love to hear from anyone who has a single source solution
which produces good online and hard copy documentation. And finally,
I'd like to offer my opinion that online info. is great, but paper
docs also serve a purpose. If documentation all goes online in the
next 10 years, it won't be because it is most advantageous for users.

Thanks, Jan
--
Jan Jackson, Technical Writer
Susquehanna Investment Group
email: jjackson -at- susq -dot- com

                  TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send administrative commands
         ALL other questions or problems concerning the list
       should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-