Documentation

I spent most of yesterday morning and this morning trying to write a section on documentation f0r chapter one. All my attempts seemed wooden and stiff. Finally I had a sort of break through. This is how the beginning of it reads now:

***************************

Documentation is a lot like flossing: nobody likes to do it, and far more claim to do it than actually do. Developers want to develop. The last thing they want to do, generally, is to take time out and describe what they are developing and how they are going about it. And yet, like flossing, few things are as important to a healthy database enterprise.

Imagine you have been hired to work as a data administrator for some company. They have a large and complex database, but the former administrator, who was also the developer, left no documentation. In order for you to do your job you need to understand each object in the database is meant to do. You also need to know it is supposed to work, how data is processed. Managers expect you to be able to provide them with the data they need when they need it. Some pieces probably make sense right away, but several pieces remain obscure. You try to ask people about them, but managers are not database designers and, generally, they don’t have a clue. Many of the people who were involved in the creation of the database have moved on, and it is difficult to get a clear sense of the original intentions or purpose of the database. Eventually you may solve the problems, but you will have spent countless hours in investigation, hours that could have been saved by a little documentation.

Documentation is one of the most important and one of the most neglected aspects of any database project. When you look at a database built by someone else, or even one that you may have made some time ago, it is often difficult to see why certain decisions were made, why the tables are the way they are, why certain columns were included or left out. Without documentation, it can take a great deal of research and guesswork to understand the database. You may never understand all of its original logic.

So what does it mean to document a database? There are really two main aspects that need to be documented: the structure of the database itself and the process by which the database was developed.

*****************************

It is still not perfect by any means, and I don't know how the editors will react to the flossing simile, but at least it flows better than what I had before.

A brief patch of sun this morning, gold, green on the new grass of the back lawn. The mountain is clear and bright with new snow, but the weather report suggests this is a brief respit.