Re: HTML as document source?

[Tim Altom <taltom -at- IQUEST -dot- NET>]

At 11:30 AM 7/18/96 -0700, you wrote:
<Bandwidth cuts reluctantly made>

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

No, there isn't. You and your programmers have confused "important,"
"accurate" and "need" with a more important factor: management. The greatest
enemy that large doc projects can have isn't inaccuracy (which can be
quickly remedied) or distribution (which can always be redesigned). It's
mismanagement, or no management. That can't be remedied without as much
effort as writing the whole damned thing all over again. I respect your
programmer's needs for maximum accuracy, but they must understand that such
accuracy isn't the question. The company's greatest need is for smooth
organization, not for pinpoint accuracy, and the ensuing time smash that
will inevitably ensue if you have to keep two huge files is far, far more
than the thing can ever return in profit.

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.

Precisely. IMNSHO, lose the online editing idea. Trounce it, shred it and
toss it in the nearest Dumpster. That's a sure way to lose control of both
accuracy and distribution. Too many cooks, etc.

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


You got it. And don't buy into that "we're a real fast-moving kinda place,
sister" argument. That's bull. Any company that moves too fast to collect
its thoughts and keep its documentation accurate is succumbing to sloppy
technique, not serving its users. You're right...the key is to keep a single
source, not permit unauthorized tinkering with the doc, and have it right
the first time. After that, it's an ECN process. It's slower and irritating
for techos who want to go-go-go, but take the time to manage. In the end you
get there faster.

Tim Altom
Vice President, Simply Written, Inc.
317.899.5882 (voice) 317.899.5987 (fax)
FrameMaker support  ForeHelp support

Makers of DuoFrame, giving you online help and paper
documentation from a single parent FrameMaker document.

http://www.simplywritten.com/simply

                  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-