HTML as document source?

[Rick Lippincott <rjl -at- BOSTECH -dot- COM>]

Angela Howard yesterday wrestled with the problem of allowing developers
to make changes to the documentation her company puts out on a web page.
The alternative was to allow her to maintain control via Frame source files.
She said:

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

Angela, I think you hit it right on the head.  The solution is a better process.
The biggest danger in letting the developers change the source documentation
lies in what will happen down the road. Because you're in a fast-moving, chaotic
kind of place, developers will go in and make changes more and more often.
The following things will start to happen. It'll be unintentional, but they
will happen:

* Developers will make a quick change and forget to tell you. You'll learn of it
   months later when you happen to stumble across it.
* Developers will change one place in the documentation, but overlook the
   half-dozen other places where the data also shows up.
* Developers will make a change to the software, and a change to the
   documentation...then find the software change didn't work. They'll then fix
   the software, but may not remember to get back and fix the documentation.
* Developers will change things with no real understanding of document
  organization or function. You'll find, months later, a small item
  buried in a small step and realize it's a major issue that required
  a major explanation.
* Developers aren't writers, and they don't have the language skills
  and writing skills that you have.
* Developers may, in some cases, view the documentation as a low priority,
  and simply never make the changes that they need to.

The process of going through you, as a form of source control, is a
bit clumsy and slower in a fast-paced environment. But it -is- a
form of control and process, and in that respect allows your company
to produce higher quality documentation as a part of the total
product package.

If your company were to ever consider ISO 9000 certification, I
think it's a fairly safe guess that you'd have some problems with
a process where there's essentially no control over who makes
changes to the documentation, or when.

The best solution, of course, won't be popular with management. By
the sound of things, you're already busy, and unfortunately the
best solution is to hire another writer to reduce the load.
Failing that, as somebody else has said on this list, your company is
faced with the classic choice: "Fast, Cheap, Accurate. Pick any two."
With another writer, you can maintain fast and accurate changes to
the source document and get them quickly into HTML, but you've lost
"cheap." By maintaining "cheap" and not hiring another writer,
you can maintain control of the source documents, and stay accurate.
Or, you can let the developers change the HTML, in which case you
have fast and cheap but not necessarily accurate.

Tough choices for management, but it's a tough world.
Good luck with it.

Rick Lippincott
Boston Technology
Wakefield, MA
rjl -at- bostech -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-