At 02:12 PM 5/27/99 -0700, Xah Lee wrote:
>My question is, how are such documentation managed in corporations? For an
>'average' database, say of 30 tables, do you guys document it at all? Is
>there a way to put text along with schema definition (create table
>statements) such that when doing a 'mysqldump --no-data', the documentation
>sticks along with the schema?
I try to document things as best I can, but I don't know of any way to get
a mysql dump to include documentation. But if you're careful, you wouldn't
need that anyway. We have a few small mysql databases that we use and I
seem to be creating more all the time (strange how mysql seems somehow
easier than Perl dbm files more and more...). What I usually do is some
documentation before the project, some during and then a wrap-up afterwards
(which becomes as detailed as the project's requirements demand).
Before I start, I write a short report that attempts to lay out very simply
what the database is supposed to do. Then I draw everything out with nice
pictures showing the table relations. I do this because it's easy to spot
the problems early on, it gives you something you can show to your boss,
and it keeps you from forgetting why you needed that one tiny table that
only has an auto_increment ID code and a date. You can use this drawing as
a base for a final drawing showing an overview of table relations when the
project is done, as well. The only downside is that if you change
mid-stream you have to make new pictures (but if your pictures change
overmuch, then you likely have bigger problems anyway). Note that a series
of flow chart-ish diagrams showing the range of possible
queries/inserts/updates/whatever count as nice pictures, and can be very
handy for a small project.
Using that diagram, I create the database, the tables, the
input/ouput/reporting scripts, etc. After each physical table creation I
do a `describe table_name;`. I use this to show the actual layout of the
table. Sometimes, I make a list after each describe output that show what
values are what, what is expected, where the data comes from/goes to, etc.
When I'm all finished, I do a no-data dump, and include with this all my
describes and the pictures. If the project is important enough (i.e., it
might outlast my job or something), then I re-write the short essay to
include more detail like what everything is supposed to do, where scripts
are, when they run, who runs them, what the table relations are, etc. Then
I package all this up and stick into the db's mysql/data/db_name
directory. (I probably shouldn't be putting compressd files in there, but
it's the only place where I know I won't forget it.) After all this, I add
the project to a list I keep that has everything I've done on it (which
aslo comes in very handy around review time).
All this is probably overkill, and it certainly lengthens the time it take
sot get anything done, but it pays off iof you have to hand the project off
to someone, or if you have to go back and fix something three years
later. Besides, your boss will probably like it. Management love
documentation.
Anyway, not really an answer to you question, but some random thoughts on a
system that works for me.
-B
Bill Rhodes
x16002 AA-202M
