8 Good Occasions to Start Documenting Your Databases

It's never too late to start documenting your databases. Regardless of the stage in it's life-cycle or your knowledge, whenever you have a chance to put that knowledge into a document. Here are some occasions that you shouldn't miss that opportunity.

1. You inherited a legacy software project

Raise your hand if you have been there. You got some legacy application, tool or database that no-one knows how it works, the guy who did it is long gone and he didn't leave his phone number nor a bit of documentation.

You don't have a clue how the system works so you learn a piece at a time. This is where you should definitely document what you have learned. For the sake of all those who will come after you.

12 likes

Dataedo Cartoon

2. You are designing and developing new application/database

Most obvious moment to start documenting is when you design and develop a new database. Unfortunately, for a number of reasons it doesn't always happen. This is the best point at which you should document a database since this when you have the most knowledge about a database and will help rest of team with the development and testing.

3. You are passing database to maintenance

OK, so you didn't do any documentation while development, you now go live with the database and you are passing it to maintenance. This is a great chance to stop here for a moment and provide maintenance team with the right tools. Database documentation is one of the things they need. Documentation, along training, is a great tool for transfer of knowledge. It's even better than training - it lasts much longer and it's much more scalable.

Even if you will be maintaining your databases yourself (your team), document database now, as you still remember the meaning of each table and column. When you will be forced to check some urgent error in a year or two you might now have a clue any more, and you will thank yourself for a documentation.

4. You are planning to do reporting or analytics

Any reporting, business intelligence or data warehouse project is a big step in a lifetime of any database. Till now it was probably accessed only by one application and code that was developed by the same team at the same time. Also, it most likely consisted of simple read/write operations.

Now, probably new people will be engaged in accessing the data and they will need to understand the data and data model well. Schema documentation is a great step in preparing for this task.

5. New people in your team

New people in your team require on boarding. You will need to train them and familiarize with the software you are developing or maintaining. As mentioned before, good documentation does the job nicely. If new people are joining your team it is a good opportunity to do the documentation if you haven't till now or review the existing one and keep it up to date.

6. Key people are leaving

If some key architects or developers are leaving your team or organization it is most likely the last chance to create proper database documentation. At least with reasonable effort. If they leave cost to reverse engineer it and discover relations and meaning of each table and column will be significant.

8 likes

Dataedo Cartoon

7. New job or a retirement

Same goes to you - if you are leaving for new job or planning retirement, please consider people you will leave behind and do them a favor - leave useful documentation.