Generating Technical and Business Documentation for Data Models

Astera Data Stack gives its users the option to generate technical and business documentation for data models (.mdl files). The resulting document (.html file) provides some details on the data model(s), including an overview of the underlying database, the tables/entities in each model, the columns in these entities, the relationships between these entities, etc.

Video

How to Generate Documentation

For a Project

When you generate documentation for a project, the document contains information on all of the data models present within the project.

In the top-most toolbar of the Project Explorer tab, there’s an option titled Generate Technical Documentation on the right side.

01-project-explorer-generate-technical-documentation

Note: The Project Explorer tab will automatically appear on the screen when you open an existing project or create a new one. If you can’t see the Project Explorer tab, click on View > Project Explorer in the main menu.

When you expand the Generate Technical Documentation option by clicking on the downward-facing arrow, you’ll see the following sub-options: Generate Technical Documentation and Generate Business Documentation.

02-generate-technical-business-documentation

You can choose the appropriate option here, based on the kind of documentation you want to generate. Please refer to the next section of this article to learn about the difference between technical and business documentation.

When you click on either of these two sub-options, the Browse For Folder window will allow you to choose a location for the generated document.

03-browse-for-folder

Once you’ve chosen a location, click OK. A new folder titled ‘BusinessDocument’ or ‘TechnicalDocument’ will be generated in the chosen directory, depending on the kind of documentation you’ve generated. From this folder, you can access the HTML document and its contents.

04-business-document

Here’s a look at the generated document:

05-html-document-data-models

On the left, you can see an expandable node representing each data model in the project. The entities in each model are arranged based on the type and schema they lie under, which forms a tree-layout under each node.

06-html-document

Each of the links provided in this layout, whether for the model itself or for an entity within the model, are clickable and will lead to a detailed overview of the item you’ve clicked on. For example, here’s what appears when you click on a model (in this case, DW_SaleNOrder, which is a dimensional model containing two facts and four dimensions):

07-data-model-documentation-GIF

Similarly, here’s what appears when you click on an entity in the list (in this case, City, which is a dimension entity):

08-data-model-documentation-entity-GIF

For an ADM Deployment

You can also generate documentation for deployed models via the Data Mode Deployment tab. To access this tab, go to Server > ADM Deployment in the main menu.

09-adm-deployment

To learn about data model deployment, click here.

In this tab, you’ll notice the same option that we saw in the Project Explorer.

10-adm-deployment-documentation

From here, you can generate a technical or business document for a deployed data model.

11-adm-deployment-document

Difference Between Technical and Business Documentation

Business documentation only provides information that is relevant to business users. For an entity, this includes basic details like database information, object overview, column and properties, etc.

Technical documentation is designed for technical users and goes a bit deeper in terms of details for each entity. These details include the child and parent relationships of an entity, and the indexes created within an entity. This extra information can be very useful when trying to understand a data model and its components from a logical and technical perspective.

Here’s what the entity information looks like in a technical document:

12-technical-document-additional-details

This concludes our discussion on generating technical and business documentation for data models in Astera Data Stack.