RE. Documenting a mess?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Kim Forbes has <<... been given a project from hell... a database product
developed by a marketing guy... The developer has no idea what tables and
queries are connected to what forms. He built the program as he went along,
did not take notes or put in comments. He has forgotten why buttons and
fields are on a form, but is afraid to take it out. The same form is called
one thing in one place and another name somewhere else. There are hidden
fields lying outside of forms and I have to pick through the visual basic
code to figure out why they are there--the developer can't remember.>>

This isn't a documentation problem, it's a software problem. Although it's
easy to understand the management problem ("we don't want to offend this guy
after he's gone to all this trouble" and "Kim's a doc genius; we're not
worried about wasting her time and anyways, she'll be able to figure it
out"), trying to fix the problem with documentation is entirely the wrong
approach. It's a truism that you can't make a really bad product usable
through documentation, but that won't convince your managers. Sitting down
with them and explaining the problems that using this software will cause
will convince them: the software will be impossible to maintain, debug, and
upgrade; it will be a guaranteed source of data-entry errors that will be
costly to find and fix; and it will invoke ongoing hostility from its users.
Ask them to sit down with you and work with it for 15 minutes to get an idea
of just how nasty it is to use. Once they have a visceral feel for the
problem, remind them of how many hours of staff time will be wasted trying
to use this abomination and they'll be much more sympathetic to your case.

<<I have to write a system admin guide and a user guide. Does anyone have
any ideas about sorting through this mess.>>

Yup. Refuse to do it, as firmly and politely as you can. This kind of shoddy
product should be redone from scratch. It would be safer, cheaper, and more
effective to hire a competent programmer to rewrite the application from
scratch than to try and fix the existing application. I find my current
signature strangely appropriate in this case.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer