Database Documentation: Latest Trends


Database Documentation is a key activity of the software documentation process. It is usually represented as a combination of written text and graphical models. In this article, we will discuss the importance and challenges of database documentation, and the latest trends in this field.

Importance of Database Documentation

Database documentation is considered essential in any software development project. We discuss here the most important driving forces for documenting databases.

The Need for Maintainable Software

As indicated by several studies, cost of software maintenance constitutes more than 50% of the total cost of software development. This number clearly signifies the importance of the maintenance phase. But how is database documentation related to software maintainability?

Software maintenance phase could last for years or decades. As a result, it is highly possible that people working on software projects forget about the structure of databases. This issue has a negative impact on software maintainability, where it becomes more difficult for programmers to fix bugs or make changes to the system. Database documentation has always helped programmers in understanding databases and making changes easily.

Mitigating the Negative Impact of Employee Turnover

When employees leave their software development job, new people are assigned to work on the projects. Because they are not familiar with the existing software, including the database, newly assigned people always find it difficult to get on board. They usually have difficult time figuring out the meaning of each database object, including tables and columns. Because of this issue, some organizations might need to restructure an existing system to be able to make changes to it.


Database documentation have always been challenging for organizations. In this section, we discuss the most important challenges to database documentation.

Uselessness of Database Documentation

Could database documentation be really useless? The answer is yes! This situation happens when the documentation is stored in documents or files that are inaccessible or unusable. Inaccessibility could be due to the fact that no centralized repository is used to store the documents. So the people who need the documentation may not know that it does exist, and if they do know, they do not know where to find it. For example, a programmer might document a database of a new system, and save the documentation on his development machine. Other people who might be working on the project in the future may not know that this documentation already exists.

Keeping Database Documentation Up-to-Date

This challenge should be recognized by all people who work in software development. To reemphasize, software usually go though many update cycles. The most popular scenario happens when a database is documented at some point of time; then developers start making changes to the database without updating the documentation. After a while, the documentation becomes incomplete and inconsistent with the current database structure.

Integrating Database Documentation with the Coding Activity

The people who mostly need database documentation are the programmers. Programmers repeatedly write code to manipulate the data in the database. To do that, they need to understand the business behind the tables and columns in order to determine where to store each piece of data, and where to read each piece of data from. Database documentations usually exist as separate documents that programmers need to read to understand the database context. The obvious challenge here is to help programmers understand the database while writing code to manipulate it.

Data Access Agility Solution for Database Documentation

Data Access Agility is a tool that auto generates the data access layer (Including persistence entities and data access objects) without writing any line of Java code or SQL query. It has numerous advantages over traditional ORMs. Data Access Agility provides a sensible solution to traditional challenges associated with database documentation. It provides the capability to specify the documentation for each table and column using the Database Schema panel.

Once the data access code is generated, programmers will not have to access any external document to understand the database. Instead, Data Access Agility will embed the documentation of each table and column in the classes that were generated by the tool. This allows the programmers to have instant access to the database documentation. To view a full sample Java code, click here.

The following screenshot shows the documentation of Employee’s type property as shown by the IDE

The following code snippet shows a JavaDoc comments that were added to the data access method. These comments are supported by most IDEs where programmers can view a documentation of the method while writing code.

* Retrieves a single record from database. The values returned are <code>{@link Employee#id id}</code>, <code>{@link Employee#number number}</code>, <code>{@link Employee#fullName fullName}</code>, <code>{@link Employee#gender gender}</code>, <code>{@link Employee#hiringDate hiringDate}</code>, <code>{@link Employee#status status}</code>, <code>{@link Employee#type type}</code>, <code>{@link Employee#salary salary}</code>, <code>{@link Employee#divisionId divisionId}</code>, <code>{@link Employee#picture picture}</code>, <code>{@link Employee#latestCheckInDateTime latestCheckInDateTime}</code>
* @param byId (filter parameter) A unique number used internally by the system. This number is not supposed to be known employees
* @return Objects retrieved from database


Furthermore, project administrators can require that each programmer enter documentation for each table and column. This feature makes sure that database documentation is always up-to-date. Programmers, however, can still use other modeling software to create a graphical representation of the database. Graphical  models are useful for understanding the database context as well as the relationships among the tables. Such models, however, does not help so much in understanding the meaning of individual tables and columns.


Create your first project at Data Access Agility

Watch a 4-minute tutorial on how to use Data Access Agility

View a sample Java code with embedded documentation