Back to articles list
Sometimes your data models speak for themselves. But for those who don’t understand their language, you need to add clarifications that explain the reasons behind your design decisions.
You may think that your database designs are works of art and therefore need no explanation. But the problem with works of art is that each person who looks at them can interpret them differently. This is fine from an artistic point of view, but it doesn’t work in day-to-day database work.
A data model is more of a tool than an artwork; as such, it cannot give rise to different interpretations. The easier it is to understand a model, the better results it will give (in the form of more efficient databases and higher quality software).
How to Communicate Your Decisions
When you design a database, you are making decisions all the time: when you normalize or denormalize a schema, when you choose the fields that will form a key, or even when you name a table. Your teammates – other designers, programmers, testers, etc. – need to know the reasons behind each relevant decision.
If you work in constant contact with your teammates, you may think it is more straightforward to verbally explain your design decisions. However, relying solely on verbal communication is not a good practice. It can be very time-consuming, especially on large teams, and the persistence of knowledge becomes dependent on each one’s memory. Verbal communication is beneficial in certain situations – such as sharing ideas, brainstorming, and so on – but if knowledge is to persist, it needs to be documented.
Agile Database Documentation
Following the philosophy of Agile methodologies, the best way to document is to do it continuously and in parallel with development. So, among the database tools you need to do your job, you should have one that integrates documentation features in the same environment you use for development.
This Agile documentation principle does not only apply to programming. You can also apply it to database design and modeling, so you need a design tool that allows you to document at the same time as you design your diagrams.
Ideally, database documentation should be part of the diagram itself so the reader doesn’t have to swap tools to understand your decisions. The Vertabelo design platform offers you several alternatives to document your designs, starting with the addition of text notes.
Adding Text Notes
A text note accompanying a diagram is the best way to convey the reason for your design decisions, since the person looking at the diagram does not need to open another document or switch to a different application to read your explanations. In the diagrams you create with Vertabelo, text notes are added in the same way you add any other part of the model structure. You just need to select the Add note option by clicking on the Text notes item in the model structure tree or by clicking the Add text note icon in the toolbox and then clicking on the place in the diagram where you want to place the note.
Text notes allow you to document decisions that are not obvious from just looking at the ERD.
In the Note properties window, you can give the note a name and write its contents. In the Format section, you can change the color of the note. (Above, we’ve used the default color, yellow.)
Documenting Versions
Another way Vertabelo lets you create database documentation is through autosaving, versioning, and change control. These features allow you to concentrate on making changes to your database model without worrying about remembering each change for later documentation.
Vertabelo’s Autosave feature generates a new version of your model for each change you make. When you want to review your work and document your diagrams, you can compare the versions generated throughout the day and attach tags to the versions with significant changes; this lets you synthetically explain changes from one version to the next. If you prefer not to leave this task to the end of the day, you can use the Set tag feature after making an important change. This lets you give the current version of the diagram a name that explains any changes.
You can use tag names to explain what changed in each version of a diagram.
When reviewing your data modeling history, maybe you find that the autosave function generated versions that have no significant changes. In that case, you can simply delete them without fear of losing any of your work.
Documenting the Code
Data modeling documentation should not apply only to diagrams. Eventually, the diagrams are transformed into the SQL/DDL (Data Definition Language) code that allows you to create or modify a physical database. SQL scripts are the deliverable a database administrator (DBA) needs to create a schema or migrate it to a new version; these scripts must be easily readable and well documented.
Vertabelo’s physical model versioning feature allows you to generate version migration SQL scripts with the assurance that the script will run without errors in the target database. To do that, you must have a saved version of your diagram that accurately reflects the database schema you want to migrate (preferably with a tag that allows you to easily identify it). You don’t have such a version? No problem. Vertabelo also allows you to generate a physical diagram from an existing database by reverse engineering it. You just need to connect the design platform to the database you want to update and the diagram is built automatically.
To generate scripts, you can use the Model migration option from the Documents screen or Generate migration from this version from the Model version history panel to activate Vertabelo’s script generation feature. The SQL generation feature has an option to include comments for database objects. It is highly recommended that you enable this option, as the comments in the SQL code are the database documentation that DBAs need for guidance within the scripts that you give them to execute.
When generating a migration script, make sure you select the option to include comments, since those comments are the documentation that DBAs need.
Using an External Repository for Version Control
Although Vertabelo performs version control and keeps a history so that you can track changes and eventually undo them, its functionality as a version control tool is limited. Users can delete versions if they have the appropriate permissions, and versions older than 38 days are automatically deleted to reduce storage requirements.(The newest version for each week is not auto-deleted.)
For tighter version control, you can keep the diagrams you create in Vertabelo in an external version management system like Git. This allows you not only to keep the entire version history (regardless of its age) and also to link and synchronize the versions of your data models with the versions of the software products that use them. This way, if version branches or rollbacks are made, your data models will accompany the rest of the solution in those branches and rollbacks, keeping the data modeling history intact. Here, you can read more about how to use Vertabelo with Git.
Other Documentation Options
The documentation options we have seen so far are mainly aimed at facilitating the work of teammates: other designers, programmers, DBAs – i.e. people who know how to look at an entity-relationship diagram or who understand SQL code.
However, documentation may also be intended for non-technical database people. They too need to know your design decisions, but they need them explained in a more “human” way than models and scripts allow.
For example, a user may need to see the table structures to verify if the data types you chose for each field are appropriate. This user will not find it practical to look at an entity-relationship diagram; instead, they will need detailed documentation showing the structure of each object in the database.
Vertabelo’s automatic documentation generation tool allows you to generate PDF documents that include all the details of each object in the diagram. Such a document can serve the function of a contract: your user can review it – and even sign it – to confirm whether the tables you created meet their requirements. You can also use any online pdf modifier tool to make edits in the document later.
Presentations and Web Publishing
Raw technical documentation may be inadequate for clients or sponsors who just need to know how an application and its database work. Therefore, letting them know why you made your design decisions is often a challenge. If you only give them your diagrams and the detailed object documentation, they will likely find it incomprehensible or tedious.
Proper documentation for a client or sponsor should be synthetic, readable, and easily understandable. The content must demonstrate that your design decisions make the database work faster, take up less space, and give 100% reliable results.
In most cases, a slide presentation, a few pages of text, or an easily navigable website is the best documentation to give to sponsors and clients. Your diagrams can be part of that documentation to highlight specific aspects of your designs. Vertabelo allows you to display them in two ways: exporting them as images so you can incorporate them into a document or presentation, or generating the HTML code to embed them in a web page.
With Vertabelo, you can export all or part of an ERD to a PNG or SVG image file and then insert it into a document or slideshow. You can then add information to facilitate its interpretation. You can also embed the ERD in an HTML page using the code provided by the Publish to web feature.
Vertabelo Provides Database Documentation Assistance
Database modelers need communication skills, which means talking to other people and conveying ideas through effective documentation. Documenting is not the most appealing task to a database modeler – especially for those of us with a largely technical background – but it is unavoidable.
Fortunately, as we have seen throughout this article, we have the help of tools that take the burden of documentation off our shoulders, freeing up time to do what we like most: creating data models and databases that work beautifully.
