Harry Slaughter, JonBob, myself, and others have tried countless times to come up with a workable solution for documenting our database schema. This either resulted in static images and so forth that were impossible to maintain, or trying to work around MySQL's comment length limitations. However, with the Schema API, the day is saved! Joy! Earl came up with this slick idea in the Views 2.0 schema to stick a 'description' attribute on each field in the schema file. Drupal will of course ignore this, having no knowledge of what a description is, but human beings (and probably eventually parsers) can read this information in order to determine what the various fields are for. Additionally, the documentation is *part of the source code*, which means we can deny schema additions until they have documentation associated, just as we deny new functions without PHPDoc. And finally, because the descriptions are stored in t() functions, that means the documentation is (potentially?) translatable to other languages. I've taken this idea a couple steps further (by adding table descriptions as well as field descriptions, and adding in foreign key information), and have started documenting all core schema files here: http://drupal.org/node/164983 I'd love help from: - Anyone at all who has some time on their hands and would like to learn Drupal's schema inside and out by helping to document the remainder of the files, using the existing patch as a guide. - Core committers, to give a thumbs up/thumbs down to this approach before we dump a bunch of time into it. ;) - Schema API folks, to give guidance, esp. on foreign key representation. - Experts on the lesser-used aspects of Drupal (aggregator module, for instance) who can clarify what some of the fields are for. - Testers, to make sure the patch doesn't horribly break things. ;) Thanks! -Angie