If you are working with databases, or you even designed them, you might have the impression that it is all obvious and there's nothing more to explain. If anyone would need something, they can always talk to you, since you know all the answers. In this article, I'd like to show many people require to understand the design and would be very grateful for a useful documentation.

Who is this? The short answer is everyone that will read or write to it directly. See who that might be in your organization.

Application Developers

Those are the guys who need to understand database schema as they write code that reads and writes data to the database. Documentation for developers should include description of all tables (with columns), views, stored procedures and functions (definition of their interface) that are used by the application.

DBAs

DBAs may or may not be the ones that create data structures. It could be done by architects or developers, depending on your organization. DBAs should have at least basic understanding of what data is stored in the database. Documentation for DBAs should include at least top level grouping of tables and programs into logical "modules" and have a knowledge of what are they used for. List of key (and large) tables would also be appreciated.

Report, BI & DW Developers

Another group that uses database heavily is everyone involved in reporting, business intelligence and data warehousing projects and activities. This group has a tough life (I know, this is what I did for years) as they are not a part of the design team and often come later when there's no-one they could ask how things work. This group requires top level documentation what database holds, where to find what data (which tables) along with detailed data dictionary and all the caveats.

Data Analysts, Data Scientists

A similar group to report and BI developers are data analysts and scientists. The difference might be their requests for data would be more ad hoc and one off. They might be interested in a broader scope of the data and jump more often from one to another. Therefore their requirement for database documentation is even more pronounced. They require knowledge of not just relational databases but all other data sources, including spreadsheets, CSV, XML and binary files.

Testers

Yes, testers often need to either prepare test data or run tests on the data created by the application. This requires knowledge of database schema, so the documentation is welcome.

Support/Maintenance Consultants

Second or third line application support consultants might need to access database to test and fix the data. When something is wrong with the data in the application form/grid or the report, then consultants must check at the source. Our team does that on a daily basis as they support our solutions. This requires a good understanding of the database - they need to know where to find the data and interpret what each field and value means.

Migration Team

When the time comes for your current application or database and your organization will be planning to migrate to some new shiny solution, the data will have to follow. Data is your crucial asset and losing it is a big threat to your organization. If data migration goes wrong, you could lose or destroy some data, sometimes in a way that gets undetected for years. To do the migration right requires a good understanding of the source data, destination database schema, and preparation of mappings. If you want to save whoever would be responsible for that from a headache and sleepless nights, prepare a documentation a head of time. Years ahead. Do it now, when you still know all the details.

Yourself

In a few months, you might not remember anymore all your design decisions, caveats, and assumptions. Not to mention how is it going to be in a few years time.

Anyone Else?

You think anyone else needs a documentation? Share your thoughts in a comment.

Start documenting databases with a free tool