Ah the beautiful data model. They say a picture is worth a 1,000 words. And then we have our diagrams, how many words are they worth?

Our friends from the Human Relations sample schema

So our models describe how the data ‘works’ – whether that be at a logical-business level, or a technical-physical level. Developers like to say that their code is self-documenting. These would be very lazy or very bad (or both) developers.

Models are the same way, you should document your models with comments and notes!

I have 3 basic options:

1. Comments
2. Comments in RDBMS
3. Notes

So what’s the difference?

Comments

You’re describing the entity/table or attribute/column. This information will NOT be published in the database. It will only be available to the model, and hence, folks with access to the model.

Table Comments (in the design only!)

Comments in RDBMS

You’re doing the same thing as above, but your words will be stored IN the data dictionary of the database. Oracle allows you to store comments on the table and column definitions. So your awesome documentation is going to be viewable to anyone with access to the database.

RDBMS is an acronym for Relational Database Management System – of which Oracle is one of the first commercial examples

If the DDL is produced and ran against a database, these comments WILL be stored in the data dictionary.

Notes

A place for you to add notes, maybe from a design meeting. Or maybe you’re using this as a to-do or requirements list. Basically it’s for anything that doesn’t literally describe the object at hand – that’s what the comments are for.

I totally made these up.

Now these are free text fields and you can put whatever you want here. Just make sure you put stuff here that’s worth reading. And it will live on…forever.