Documentation (mis)management

[geoff-h -at- MTL -dot- FERIC -dot- CA]

 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
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html