List:General Discussion« Previous MessageNext Message »
From:Bill Rhodes Date:May 28 1999 12:50am
Subject:Re: schema documentation
View as plain text  
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
Thread
schema documentationXah Lee28 May
Re: schema documentationScott Putman28 May
Re: schema documentationBill Rhodes28 May