Re: documenting a mess

["Tim Altom" <taltom -at- simplywritten -dot- com>]

My first impulse would doubtlessly be to hand back the entire swamp, along
with my resignation. But that's a bit of overkill, methinks. Although, the
thought of passing along something that potentially explosive should scare
the bejabbers out of any decent IT manager.

Our typical outlook around here is that we have two answers to every
question a client or prospect poses: "Yes", and "Yes, but..." Given enough
time, energy, money, manpower, and patience, anything can be made to work.
The question is whether the fox is worth the chase. If your employer has
already made that decision, you're stuck. But you're not powerless.

We've found around here that numbers are extremely potent. If you can study
this project and start making some good projections about time and other
costs, you have some extraordinarily powerful tools with which to get your
own way. For example, if it turns out you must literally team with a VB
person to pick through the code in order to properly document it, then ask
that person to give you an idea of how long (in both person-hours and
calendar hours) it would take to do that. Make sure you keep these data,
because your pleasure or hatred of this job may depend on it. Any project
can be made enjoyable if you know in advance that it's doable, and that you
have the resources budgeted with which to do it. If you can defend a claim
that it will take you six months to do even a passable manual, then make
your case and lay claim to those resources now. Try to forestall
management's carping after a month. "I warned you..." Often even the
crustiest boss won't challenge carefully-crafted numbers.

As to how to document the stuff itself...well, here's where the witchcraft
in our business lies. You can approach it essentially from one of two
directions: from the interface, or from the code. If you start from the
interface, you'll have to click, point, jiggle, and type things to see what
works how. That'll take a load of time. Take the number of screens  and
multiply by, oh, say, a day per to test. You won't be thorough, but it may
be enough.

You can, alternatively, approach from the code side, teasing apart the
various form control definitions and documenting them, in hopes that it'll
all come together in the end. Again, not a fast thing to do. And you'll
still have to document the "what" at some point.

You can combine both approaches somewhat, but I don't advise a 50-50 split.
It's too confusing and you'll wind up spinning your wheels a lot.

What I advise, in fact, is that you take a task-based approach. That is, you
sit down with the developer and make up a long list of the various tasks
that the software may be called upon to perform FROM THE USER'S PERSPECTIVE,
NOT FROM HIS! When this list is in your hands, then sit in front of the
interface and figure out how to make the crap work from Step One through
Step X. Then move on to the next task. It's how we teach people to document
in the Clustar Method, and it works great. You can get traction on the job
immediately and you and the developer can find common ground without
arguments.

It also simplifies your job. First, you don't need to pick through much
code. Second, if there are extraneous buttons or menu items, you don't need
to figure them out, either. Third, you get a handle on the paradigm
immediately. Fourth, it lets you test the interface and get a bug list
together, without the need to actually KNOW the interface when you start.

Forget about doing a complete list of buttons and menu items. Most modern
apps have too many for the user anyway, and manual pages with them don't get
used very often. Bear down hard on the controls that are used with the tasks
and ignore the rest. Nobody will care.

I feel for you. But my advice for survival is to do a project plan so your
enormous investment is noted and approved ahead of time, and make the
project task-based, to cut through the controls-tangles.


Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar(TM) System
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info
http://www.simplywritten.com


> Hi All,
> I have been given a project from hell.  Usually we get our software from
> outside venders, and because we are a children's hospital we customize it
> extensively. I document the newly customized products. Other times our IS
> department builds customized programs and I document them.
> The worse scenario is when a techie-inclined doctor or marketing-type
> decides to develop a product. Because doctors have a lot of power here, it
> happens frequently.