TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
>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
* 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
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.
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-