TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
Senior Technical Writer
jposada -at- book -dot- com
"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
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.