HTML as document source?

[Angela Howard <angela -at- SB -dot- AOL -dot- COM>]

The company I work for produces software that is distributed over the Web.
The manual is produced in both printed form (using Frame) and in HTML (by
converting the Frame files to HTML with Webworks Publisher).  Users can
download the software for free and read the documentation online for free.
If they want to pay some extra bucks, they can buy a hardcopy version of the
manuals (four books totalling about 800 pages).

The end result is, only a small percentage of the users have the hardcopy
manuals.  This is important, because recently (just yesterday, as a matter
of fact), some of the developers decided that this meant the online version
was more important.  In a way, I agree.  But the way this came up was
because they were reading the online version on the Web, saw some things
that needed to be changed, and wanted to change it right there on the spot.
(They can do that, because we make WYSIWYG web publishing software that will
let them edit and browse pages at the same time.)  Of course, that meant
that I would later have to go back and figure out what they changed and make
the same changes to the docments in Frame, because that's where the "source"
is.  They even agreed that that would be an unacceptable situation for me
and then suggested I come up with a way to make the online version the
"source" (because it's more "important") and generate printed docs from that
so we wouldn't run into this problem anymore.

I, of course, explained that while I agreed that the online docs were more
important, the printed books still had to look professional because people
were paying money for them and wouldn't settle for printed HTML pages.  I
can use Frame as the source, because it has all the features that let me
produce high-quality books.  When I convert Frame to HTML, it strips out a
lot of stuff. I can't start with HTML and then expect to run it through a
conversion tool to add back in all the fancy formatting.

The problem as they see it is that they can't make changes to the manuals
online, because the source is in Frame and I'm the only one who uses Frame.
That means all changes have to go through me, and right now I'm working on
another higher-priority project and don't have time to have them explain the
changes to me, make the changes in Frame, and re-convert the affected
sections to HTML.  Now, this is not an ego thing where I want to have total
control.  I really don't mind them making changes, because they only make
changes for the sake of technical accuracy, and they always tell me what
they changed so I can review the wording.  The problem is that they're not
changing the source, so everything has to be done twice.

Is there some solution to this that I'm missing?  If so, please point me to
the tool that will let me do it.  What we need is to two complete sets of
documentation, with identical content, in both printed books and HTML.  I
really don't see how HTML could be the source.  I suppose the information
could be stored in some sort of document database and then imported into
both places, but they still wouldn't be able to edit the stuff online
because it still wouldn't be the source.

I suspect the solution is just a better process, where the information is
thoroughly reviewed BEFORE it goes online and I have the time in my schedule
to make the changes to the source.  However, this is a pretty fast-moving,
chaotic kind of place (like many software companies I've worked at), so I
want to make sure that's really the only solution before I take on the
formidable task of trying to change the way things are done around here.

Thanks for everything; this really is a great list!

Angela Howard
angela -at- sb -dot- aol -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-