[documentation] [task] DB dictionary

[webchick]

Issue status update for 
http://drupal.org/node/55937
Post a follow up: 
http://drupal.org/project/comments/add/55937

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     tasks
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  Zen
 Updated by:   webchick
 Status:       active

My preference is to embed this in the actual database.mysql file as
discussed here: http://drupal.org/node/28046 -- for a few reasons:


1. Once the "up-front" work is done, it becomes much easier to enforce
that any future database column/table additions *MUST* have comments
attached to them in the .mysql file. It becomes a basic QA thing, like
PHPDoc above functions.
2. #1 ensures that there will always be _some_ level of current,
correct documentation attached to the database level. As opposed to now
when probably 30 people have all gone and written some partial semblance
of database documentation but never finished it, or it grew out of date
because they didn't have a chance to maintain it, etc.
3. It's not a separate document that must be gone through and updated
by someone whenever there are changes. Take the Forms API Reference,
for example, which is constantly out of date.
4. Various tools can auto-generate documents like a data dictionary,
E-R diagram, etc. from SQL files with embedded comments.


The way Harry and I were headed before we both got insurmountably busy
was to setup the schema with table relations in the PHPMyAdmin tool,
because it would create a standard set of comments to illustrate table
relations. These could both be read by humans to figure out how tables
fit together, and also parsed by tools to create diagrams.


What's cool about your script is that:
a) It's fairly complete
b) The coding follows a pattern so the details in it could probably be
parsed out via regex and put in database.mysql like we had wanted to to
begin with (note: I'd love to, but I can't volunteer for this -- I know
my schedule to well :\)


IMO, developer documentation is critical. It therefore needs to be a
community-managed process, and should not rely on a single
individual/individuals to keep it up to date. The best way to do that
is to integrate the documentation directly into core.




webchick



Previous comments:
------------------------------------------------------------------------

Sun, 26 Mar 2006 14:03:26 +0000 : Zen

Moshe Weitzman put me onto:
http://cvs.drupal.org/viewcvs/drupal/contributions/docs/developer/database/README.txt?rev=1.2&view=markup


I have possibly outdated, slighly incomplete and semi accurate (my
marketing skills need brushing up?) docs in my sandbox -
http://cvs.drupal.org/viewcvs/drupal/contributions/sandbox/zen/db_dictionary.php?rev=1.1&view=log


It's atm just a standalone PHP file.


Cheers
-K