Dynamic Documentation of Power BI Reports
From the 10,000 foot view, there are two sides to reporting and insights: creation, and consumption.
One side brings insights to life, while the other uses them to stay informed and make decisions.
And in between these two sides sits communication.
Directions of Communication
For one, there is the communication of requirements from the consumers to the creators.
Then, there is the communication of functionality and descriptions from the creators to the consumers.
This article is about that second type of communication.
It is about creating documentation to fit in with your consumer's workflow, without cluttering up the interface.
Documentation
A solid set of documentation will reduce the number of repetitive questions received about the report and enhance its value by improving its usability.
It's not enough for documentation to exist, however.
Making it easier to access the specific piece of information when it is most needed goes a long way to making sure that it gets used.
Dynamic Documentation of Power BI Reports
The above video shows my preferred method of in-report documentation.
I don't know if it's got a name, so I refer to it as the Three Layer Approach to Documentation.
Three Layer Approach to Documentation
The premise of the three-layer approach to documentation is that different people, at different times, need different levels of detail.
Layer One: Name
You have the first level, which is the name of an element, and necessarily terse.
This layer will be enough for those who frequently use the report when viewing a metric in their usual context.
Layer Two: Short Description
The second layer is a short description that will give someone unfamiliar with the metric a better chance at understanding what it is calculating.
The user can see this right in the reporting interface, alongside the chart showing the metric.
It may seem like overkill for basic metrics, but for others can be the difference between a frustrating head-scratcher and an enlightening insight.
"Cohort Repeat Percentage"??
Layer Three: Extended Description
Layer three is where we free ourselves from the constraints of the reporting interface.
This third layer is for when consumers require details about the how and why of a metric.
We provide this as a dynamic link to the relevant section of the external documentation.
Rather than throwing the manual at our consumers, we open it to the correct page and place it in front of them.
How it is Built
Existing Report Structure
This implementation is for reports that use selectable metrics for a single visual or set of visuals - an approach that makes for highly flexible insight systems.
Join the Ground Floor Analytics mailing list to be notified when I write an article about implementing this structure.
Elements
The Three Layer Approach to Documentation uses the following elements.
Slicer to select the metric and show the first layer
A smart narrative/textbox to display the second layer
A table with a dynamic Web URL to link to the third layer
A measure for the displayed text of this link
Implementing Layer One
With the selectable metric structure in place, we already have a table that lists our metrics' names and a slicer that displays them.
So layer one is already in place.
Implementing Layer Two
Layer two requires an additional column in that existing table of metric names.
This column includes a short, informative description of the metric, which will fit within a small space.
We then add this field to a textbox.
When we select a metric in the slicer, it will now filter this description box along with the data.
Implementing Layer Three
Layer three requires a few more things:
A set of documentation where individual sections are accessible by URL
A further column in the same table of metric names - the URL
A measure to create the dynamic link text
A table to place this URL in
This snippet shows the process of adding this link using a table visual.
Note that to remove the unnecessary table header, we hide it behind the second layer.
In Closing
By having user-friendly and accessible documentation, you can enhance the value of your business intelligence implementation by adding clarity and even broadening the audience.
The approach outlined above is one way to achieve this objective.
I'd love to hear your feedback on this approach to documenting reports in Power BI.
You can contact me directly at daniel@groundflooranalytics.com.au, or leave a note on the LinkedIn post where this was initially shared.