I strongly believe that it is key to describe everything that you have built as part of your Power BI model. As we all have a hate-love relationship with documenting our work, the external tool that I build to document your Power BI solutions could come in useful. In particular everything you add and only exists in your model is important to describe properly. This documentation is key once you share your data model with others and they try to understand the goal of a measure, column or anything else. Other than that, documentation also comes in useful if you handover your solution to your colleague or client.

As I believe it is important for everything that is only part of your tabular model, what exactly does only exist in my model? Well, if we look at tables and columns, they are (mostly) coming from a source system. Hoping that the definitions of these tables and columns are described there or by using any other sort off data management and data dictionary tooling. I said hoping for a reason. To my experience, this is not done often or only partly. And in those cases where the definitions are described properly, we should always ask ourselves, is it still up to date?

All that aside and taking the assumption that it is described somewhere, you will still have objects left that are created and only exist in Power BI. The first things that might cross your mind are Measures and Calculated columns. But that is not all! Do not forget about Row Level Security! This is also something specifically that is added to your Tabular Model and does not exist in any other system. In this blog I will describe how you can add functional descriptions to these three objects as part of your Tabular Model.

Describing (Calculated) Columns and Measures

Let’s start simple with describing (calculated) columns and measures in Power BI. Columns that are added in your Tabular Model (Power BI model), can be generated either in Power Query or in DAX. For both applies that they will become of your model in the end. Although the Query Editor offers a description field as well, I would recommend documenting them all in the same place. Therefor I would suggest to use the native functionality that Power BI includes for adding descriptions, as part of the model view.

For measures, the same applies. After creation, they will show up in your model view. With that, it is possible to add a description to each of them in the Model view. In order to do so, you have to select item where you want to add the description in the Fields pane on the right-hand side. After that, you will find the Descriptions field in the Properties pane next to it, where you can add the functional description. The big advantage of doing this, is that these descriptions will also show up in the Report view if you hover over a measure or column as below image shows.

Also check out the trick that Reid Havens shows in his YouTube video to add the DAX Measure Expression to the description field using Tabular Editor. As he explains, this can come in useful if you connect to a Power BI dataset in the Power BI Service. Personally, I prefer adding functional descriptions, especially if you share the dataset for self-service purposes, they might not be familiar with DAX and lead to confusion. So, think about the goal and audience of your dataset to decide what works best in your situation.

Describing Row Level Security roles

Now, I already shortly mentioned Tabular Editor, this is where we have to do our next trick to add a description to our Row Level Security roles. As the Tabular Object Model, which contains all the metadata describing your model and what you created, does contain a description field for roles, how useful would it be to add descriptions to each role as well?!

Power BI Desktop does not contain a native option to add descriptions to your roles, as the dialog to configure roles does not contain this field. Of course, you can decide to add the description in your DAX expression if you like. By adding a double forward slash, you can add free text in DAX.

To my opinion, it is cleaner to add the description to the actual Description field in the Tabular Object Model. As already mentioned, we cannot do this within Power BI Desktop. Here you can benefit from Tabular Editor and the read/write capabilities to your Power BI model.

When you opened Tabular Editor and connected to your Power BI model, you can add descriptions by navigating to the Roles in the left-hand menu. Once you click on a role, you can adjust the properties in the bottom section. In my example you can see that I added the same description as I added as comment in the earlier example. After changing, do not forget to click the save button and save the changes back to the opened Power BI instance.

When you are using the Power BI model documenter, the description field as explained above will also show up in the output of the Power BI model documenter version 1.2.1 or later.

Wrap up

With this blogpost, I hope I convinced you a bit more about the importance of documenting your Power BI and Tabular solutions. Especially for everything that does not exist in downstream source systems, it is important that you document these items before you finish and hand-over your solution.

This applies to (Calculated) Columns, Measures and Row Level Security roles, as this is something you create in your Tabular (Power BI) Model. Knowing the description field is only available in the model view for Tables, Columns and Measures, consider using third party tooling like Tabular Editor to add description for Row Level Security roles. If you prefer to do so, you can use Tabular Editor for any type of descriptions that you want to add.

Links

• Model Documenter external tool for Power BI
• Documentation Tabular Object Model
• YouTube Video Havens BI – Showing DAX Expressions when using Power BI Live datasets
• Tabular Editor website
• Release overview Power BI Model Documenter