[Author Prev][Author Next][Thread Prev][Thread Next]
[Author Index (this month)][Thread Index (this month)][Top of Archive]

Re: Document the detritus?

Subject: Re: Document the detritus?
From: "Kat Nagel, MasterWork Consulting" <mlists -at- masterworkconsulting -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 15 May 2003 13:51:43 -0400


At 10:42 a -0400 2003-05-15, John Posada wrote:

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.
[...]
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?

I vote for inclusiveness. When I faced a similar situation (for a MUCH smaller system) I documented the obviously real components in appropriate detail. The scraps went in an appendix with the name of the table, dates of creation and last modification, the size, name of owner, and a brief description such as:
"VBALLSTATS
Created: YYYYMMDD
Last modified: YYYYMMDD
Size: 2.3 GB
Owner: <name of former employee>
Appears to be annual rosters and scores for
a team that lost every game from 1982-1997."

The appendix was called "Do we need this?" Shortly after I submitted the draft for review, I was told that a copy of the multi-page appendix appeared on a sysadmin's desk with a big red NO! next to the heading. Most of those tables were gone when I did the revision a few weeks later.

--
Kat Nagel
Inclusiveness. Inclusivity. Whatever.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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: http://www.ehelp.com/techwr-l

---
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
http://www.raycomm.com/techwhirl/ for more resources and info.


References:
Document the detritus?: From: John Posada

Previous by Author: Apology RE: English isn't the native tongue of ...
Next by Author: What to look for in a formal English reference
Previous by Thread: Re: Document the detritus?
Next by Thread: Re: Document the detritus?

[Top of Archive] | [Author Index (this month)] | [Thread Index (this month)]

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

Sponsored Ads