Power BI Documentation and Keeping Your Future Self Happy

You're building a report against a deadline and you reach for a measure but there are two with nearly identical names, which one do you need? You can't remember and need a refresher to remind yourself exactly what each one is for and which one you need now in the current context. In the end, it's too confusing or takes too long to understand the difference so you create a new measure for your use case.

You've now added even more confusion: Why have we got three nearly identical measures? Without any documentation you end up exasperated and thinking if only I could get inside the developer's head and understand the context / use-case for each measure.

Here are two simple ideas that might help alleviate this pain.

1. Power BI Description Box

There is a field in Power BI desktop which I use which is free-type and allows the developer to describe what each measure actually does. This field can be found in the Modelling view:

Because this is free-type, you can go beyond naming conventions and properly describe what the measure does.

A further benefit is that this can serve as lightweight documentation. By using the DAX INFO functions, these descriptions can be extracted from the model and used as a basis for model documentation outside of Power BI:

One final benefit is that this description appears on a hover over. So when you're in the canvas creating a new visual and you want a measure but aren't sure which one you need, if you go to the Data panel on the right hand side and hover the mouse the description will appear:

This enables you to select the correct measure quickly and without having to change context and thus improves the developing experience.

I've talked about this in relation to measures but every object (tables, calculated tables, columns and calculated columns) has a description box so this approach can be applied across all objects in the model.

So next time you create a measure, spend an extra 20 seconds adding a description in this box. Your future self and fellow developers will thank you.

2. Measure, Calculated Column and Calculated Table Commentary

In addition to the description, when I create measures I also add in a line at the top of the measure to explain what the measure is and where the requirement originally came from, plus adding in basic details such as the date I created this measure, the reference number of the item from the sprint board and my initials.

This example below shows a measure which was created to produce a dynamic title on a line chart:

Again as this is free-type the developer can be quite descriptive and adding in the work item gives background as to why it was needed in the first place and helps others understand that context. But, obviously keep this commentary snappy, a couple of sentences should be enough. No need to write a book!

I've had some positive comments from other developers in the team about this approach and have seen that they have adopted it too.

Another simple little way to keep measures well documented and understood across the team.

Both of these methods take seconds to implement and could save hours of confusion later. Try them in your next report, your future self will be grateful!