Documentation (mis)management

Subject: Documentation (mis)management
From: geoff-h -at- MTL -dot- FERIC -dot- CA
Date: Fri, 11 Apr 1997 14:15:55 -0500

Susan Brown described documentation hell: constantly
changing targets and priorities. The long-term solution if
your company expects to stay in business is to put a
management process in place; the current process (or lack
thereof) sounds like it's guaranteed to produce buggy
software that will fail to meet the contract requirements.
A good start would be to define a functional specification
for the software (based on the contract) and design to meet
that specification, rather than someone's whim of the day.

This also suggests a partial solution to your current
dilemma: somewhere, such a specification must exist, even
if only in the minds of the programmers. Use this as the
basis for your documentation, and focus on triage: users
will be unable to use the software if they don't understand
certain facts (document these first), will be able to work
with the software with some difficulty if some facts are
obscure or missing (document these next), and will complain
about unpleasant but harmless glitches without being unable
to work (leave these until the revision).

I assume that the software you're discussing is stable on
the large scale? That is, the "File" menu may change to
"Fichier" and back again every week, but there is probably
still some menu that deals with file management. Similarly,
there's probably some function for setting user
preferences, whether it's called setup, preferences,
parameters, or customisation, and whether it's on the file
or utilities or tools menu. Produce documentation that says
"menu for file operations [finalize the name later]" and
"menu choice for setting preferences [finalize name
later]", then write down in very general terms what that
function does. [If they can't even decide from one week to
the next that there should be a File menu, abandon ship...
it's sinking so fast even the rats won't have time to
escape.] As things become more stable, be more specific. If
you can't be more specific, be helpfully vague: provide
enough context that users can figure things out with a bit
of skull sweat.

Over time, the interface will begin to freeze... parts of
it will stabilize as the programmers abandon them and move
on to new challenges. This is the time where you can start
nailing down some of the details. By now, you probably have
some idea of which parts they're happy with and which parts
they're going to keep changing right up to the end. For the
latter, consider providing these as a "readme" file of some
sort so that you can at least complete the high-level
documentation ("here's everything you need to know to
figure out the software on your own"), and leave the
low-level stuff ("here's the details so you won't have to
figure them out on your own") until the end.

Good luck. Someone else has already advised you to try to
seize control of the situation, and I'll second the motion.
I'm 100% certain that the programmers are no more satisfied
with the situation than you are, and would be more than
happy to have someone impose order on their chaos. Just be
careful whose toes you step on in doing so... it's hard to
hide in a small company if you make an enemy. Appeal to
everyone's self-interest and you should succeed.

--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca
Disclaimer: Speaking for myself, not FERIC.

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
Search the archives at or search and
browse the archives at

Previous by Author: Paper for proposals
Next by Author: Mice?
Previous by Thread: Advice sought re: TW & Disability
Next by Thread: huh? (new publication announcement)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads