Re: How to make a good documentation of a database ?

What we are doing here is likely not applicable to you, but I'll still
tell it:

- keep the data definition in an XML document, which includes all the
comments about all the tables/fields in the schema;
- generate both the database schema and the (HTML) documentation out of
this XML using style sheets;
- keep the XML in CVS for version control;

The HTML docs are also diffable between versions, but we don't keep them
in CVS as they can be readily generated from the version controlled XML.

When we have to update our schema, we update the XML data definition,
and regenerate the docs. We also have an XML schema which makes
table/field descriptions mandatory in the XML, so the busy developer
will not forget them.

Now it's clear that this needs a quite elaborate framework, and it took
some time for us to make it work, and it doesn't work always without
problems, but it is an option. For us the main reason to do it this way
was that we could abstract the XML such that we generate the schema for
Oracle and Postgres from the same data. But this "multi-db" part of it
is quite hard to achieve/maintain, and if you target just postgres, it
is somewhat easier.

HTH,
Csaba.

On Thu, 2004-11-18 at 17:11, David Pradier wrote:
> On Thu, Nov 18, 2004 at 03:02:59PM +0000, Matt wrote:
> > > The problem is, I don't want to use a lot of time to maintain this
> > > documentation, and above all, I'd prefer not to insert the information
> > > twice (read: a new constraint in the database should automagically
> > > update the documentation).
> >
> > It's a while since I've used them (just coming back to postgres after
> > enforced exile in mysqlville) but last I checked:
> > http://gborg.postgresql.org/project/dbutils/
> > Could generate UML diagrams from your DB. You might still be stuck
> > diff-ing them when you change the db, but at least they're prettier than
> > pg-dump.
>
> Thanks for the link, it's interesting :-)
> Not totaly perfect, still :
> I'll have to modify the schema of the database a lot during the next
> months, so I'd prefer not to have to do a lots of diffing between the
> database description and the 'comments documentation'.
>
> Maybe the perfect solution doesn't exist yet ?