Document the detritus?

Subject: Document the detritus?
From: John Posada <JPosada -at- book -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 15 May 2003 10:42:16 -0400

Hi, guys...I'm creating a Design Document that describes all the elements of
a computer system. It is done in the form of tables, lists, charts,
diagrams, and flowcharts...very little procedural stuff, that's saved for
the Run Book.

Most of the content is output of various database and SQL analysis tools.
Because these tools do not discriminate between "real" tables and such, and
scraps that are scattered around or left behind, I get obsolete or replaced
elements that are not used anymore, but not removed from the system.
Example. I have a table called XXXX, and a table called XXXXX_Alan_031703.
Obviously, the second file is not part of the "real" system.

Now, I could take the time to research each of these at the expense of a
great deal of time and remove them, but I don't know that I should.

After all, they are part of the system. They may not be used, but they are
there; they are taking space.

So, I guess the question is should I clean up the documentation to represent
the way the system should be, or should I take the position that the
document is what the system IS?

On the plus side of keeping the scraps in, it may prompt management to
initiate a system-wide cleanup program.

John Posada
Senior Technical Writer
jposada -at- book -dot- com
NY: 212-414-6656
Dayton: 732-438-3372
"There are those who look at things the way they are, and ask why... I dream
of things that never were, and ask why not?"
-----Robert Francis Kennedy, 1968 presidential campaign


Robohelp X3, from eHelp, lets you quickly and easily create
professional Help systems for all your Windows and Web-based
applications, including Net.

Order RoboHelp X3 in May and receive a $100 mail-in rebate, PLUS
free RoboScreenCapture and WebHelp Merge Module.

Order RoboHelp today:

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.


Previous by Author: RE: Documenting Wizards
Next by Author: RE: Document the detritus?
Previous by Thread: Re: Somewhat OT: Tech Writers vs. other writers
Next by Thread: Re: Document the detritus?

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

Sponsored Ads