Re: HTML as document source?

[Peter Gold <pgold -at- NETCOM -dot- COM>]

Angela:

The engineers probably don't create specifications or write code "from the
hip", but it sounds like they might if they think docs should be written
this way. You said it yourself below, you need a system. To extend your
description of their suggestion, why not let all website visitors "carve
their initials" in the HTML source whenever they find a way to "improve"
it? You'd probably see documents evolve similarly to the way threads on
this list do. Is this any way to run a railroad?

Regards,
__________________peter gold pgold -at- netcom -dot- com__________________
        "We shape our tools; thereafter, our tools shape us.
          We ape our tools; thereafter, our tools ape us."
________...Marshall McLuhan, based on Ted Carpenter's idea_____


On Thu, 18 Jul 1996, Angela Howard wrote:

> 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- 




                  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-