Re: documenting a mess

Subject: Re: documenting a mess
From: Bruce Byfield <bbyfield -at- axionet -dot- com>
To: techwr-l digest recipients <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 12 May 2000 10:03:54 -0700

"Kim Forbes" <kim_portonova -at- hotmail -dot- com> wrote:

>Well I have been given the job of documenting a database product developed
>by a marketing guy. It is horrible. 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 sounds like an example of what I call "Byzantine
complexity": something that is complicated, not because it's
based on difficult concepts, but because it's poorly organized.

Since the software is poorly organized, all you can do is take
extra time to make the documentation as well-organized as
possible. Besides taking time on the actual ordering of
information, plan on lots of headings, and a very incomplete
index. Consider multiple TOCs, too, with additional ones for
fields, table and graphic captions, or whatever else seems
necessary. Users may not be able to learn any general pattern to
the software, but at least they will be able to look up what they

Finally, you should make very clear to the Powers That Be at the
company that this documentation is going to take longer, and why.
Probably, you're not in the position to refuse the job, as one
poster suggested (although the temptation might be
overwhelming!), but, by explaining the problems, you might be
able to avoid a repeat.

Bruce Byfield, Outlaw Communications
"The Open Road" column, Maximum Linux
3015 Aries Place, Burnaby, BC V3J 7E8, Canada
bbyfield -at- axionet -dot- com 604.421.7189

"I'll never get to heaven, no matter what I do,
I'll never be a blue-eyed boy, although my eyes are blue,
And I will not work, and I will not work, and I wll not work for
-Ian Telfer, "The Generals Are Born Again"

Previous by Author: RE: Drawing with FrameMaker
Next by Author: Employee experience dilemma....
Previous by Thread: RE: Documenting a mess
Next by Thread: Re: Documenting a Mess

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

Sponsored Ads