Back to articles list
- 6 minutes read

How to Generate Documentation in Vertabelo

Entity-relationship diagram (ER diagram) documentation is an important part of any database project. Find out how to use Vertabelo to generate database documentation from SQL.

Writing good documentation is as hard as writing good code. Some say that teams who don’t invest in good documentation early on pay a high price later. Databases and data warehouses are central to business applications. Just like an application mandates good reference documentation for APIs, SDKs, repositories, etc., data models also need to be documented to understand the database, capture changes, and ease future development.

Many different approaches are commonly used for ERD diagram documentation, such as text annotation within the data model, text documentation, SQL model documentation, etc. You can use more than one approach to create documentation for your data model. This article will explain the benefits of documentation and explore the ERD documentation methods offered in Vertabelo.

Why Is Documentation Important?

Data model documentation should not be seen as a mere formality. There are many use cases where documentation is very helpful.

Documentation acts as the map to your data model. It helps you easily navigate the model with the help of images, text, and SQL DDL code. When all the information mentioned above is readily available, you can use the documentation to understand the current state of the database system, think about future changes, and even debug issues.

Data model documentation isn’t just helpful for the application and database administration teams. It helps everyone who will consume the model’s data downstream, such as data engineers, analysts, etc. In ETL, the data model for a source database is central in defining the ETL processes that load the data into the target system. Good ER diagram documentation helps a lot in such scenarios.

Generating Documentation in Vertabelo

There’s no single standard way to create ERD diagram documentation. You can export the data model as an image and annotate that image with text later, as and when required. You can also export the data model DDL, which could well be the only piece of data model documentation you have. Conscious of the need for good documentation, the Vertabelo team built in as much assistance as possible; they provided four different options in Vertabelo for automatically generating data model documentation. Let’s discuss each of them individually.

Exporting the Model to an Image

You can use this feature to export your data model as an image. A single image for complex data models can be challenging to navigate. Using the What to print option, you can choose a part of the data model to export as an image. This is very useful when you have already created logical groupings in your data model, i.e. using subject areas. To export your data model to an image, go to the main toolbar and select Export model to image, as shown below:

How to Generate Documentation in Vertabelo

You can choose your desired image file format (SVG or PNG); select SVG if you want your images to scale up without losing quality.

How to Generate Documentation in Vertabelo

Exporting the Model to PDF

People who work with complex data models daily might find it helpful to have a printout at their desks. Vertabelo’s Export to PDF  feature allows you to print your data model by first exporting it to a PDF file. To generate the PDF file for printing, go to the main toolbar and click Export model to PDF file, as shown below:

How to Generate Documentation in Vertabelo

A pop-up with an option to GENERATE the PDF file will open. Once generated, you can download the file.

Data models come in all shapes and sizes. They are organized differently by different teams; there’s no universal way to organize a database model. Considering that fact, Vertabelo gives you options to change the page size, orientation, margins, breaks, and footers. You can make these changes by clicking on the Format option or going to the Format tab in the Model Properties sidebar, as shown below:

How to Generate Documentation in Vertabelo

For more information on how to configure the printouts, see this Vertabelo blog post.

Generating an SQL Script

Until now, we’ve seen two features that concentrate on the visual aspect of the ER diagram documentation. However, one of the essential documents for an engineer or an analyst using the database is the DDL. Let’s learn how to generate SQL model documentation using Vertabelo’s SQL script generation feature.

The SQL script generation feature is also central to the concept of migration scripts. Databases change from time to time. To migrate data from one state to another or one version to another, Vertabelo’s Generate SQL preview comes in very handy. Our blog has additional information on generating migration scripts in Vertabelo.

How to Generate Documentation in Vertabelo

In the image below, you see the options to generate a create or a drop SQL script for the selected data model objects:

How to Generate Documentation in Vertabelo

Generating Model Documentation

This is a text-based export of all essential data model information into a well-formatted and well-organized PDF document. To generate this document, go to the Generate model documentation option in the main toolbar:

How to Generate Documentation in Vertabelo

Once you click on the main toolbar option, you’ll be asked to choose between one of three formats ( PDF, HTML, or DOCX). Each format serves a different purpose. Although you can edit the documentation after exporting it to any format, editing is easiest in the DOCX format. If you want to upload this document to a central repository, PDF might be your best choice. Finally, choose HTML if you're going to host this on a public or internal website or in your Git repository.

How to Generate Documentation in Vertabelo

Other ER Diagram Documentation Options

Publishing to the Web

You can publish the data model on the web by simply choosing the Publish to Web option:

How to Generate Documentation in Vertabelo

Once you publish your data model online, it will be available to anyone with the link. (This is what a data model on the web looks like in Vertabelo.) You always have the option to unpublish the data model, as shown below:

How to Generate Documentation in Vertabelo

Exporting the Data Model

Although you can export the data model to an image or PDF using the menu bar, you can also perform the same action using the Export option, as shown in the image below:

How to Generate Documentation in Vertabelo

There’s also an option to export to an XML file, which can also be obtained using the Vertabelo API.

Share Your Thoughts on ER Diagram Documentation

ER diagram documentation is a tedious task, especially for data models with many tables and subject areas. We believe that database engineers and analysts should spend time creating features rather than manually creating documentation.

In this article, you learned the different Vertabelo features that automate data model documentation while still leaving room for you to add additional information about the documentation. It makes your life easier!

We’d be happy to learn about your experiences in database and ERD documentation. Let us know in the comments section or write to us at contact@vertabelo.com.

go to top