Documentation in BI reporting
Importance of documentation in BI reporting
Written by our Consultant Alix Vanbrussel
It seems rather obvious, yet documenting is often taken lightly or sometimes even overlooked in projects. Every employee working on BI projects has probably experienced the frustration of limited documentation or maybe even having no documentation at all. With the current culture of self-service BI  it becomes even more important to document complex queries on datasets or intangible data models. That is because reports have now become accessible to multiple business colleagues.
In what follows we’ll elaborate on why you should document regarding BI reporting. We will also explain what and how you should document (in other words what are the important aspects of BI documentation). Finally, some examples of tools will be given to facilitate documentation of Power BI reports.
Why should you document?
There are multiple reasons why you should use documentation in BI reporting projects, but we will focus on the main three.
- Firstly, one of the biggest benefits of documentation is transferability. It is important that when an employee is absent, a new employee can easily take over his/her work. Having a supporting document for each project can prevent confusion for and mistakes made by a colleague who does not have previous knowledge about the dashboard/tables in the report. This person can then simply read the necessary information and make the adaptations asked by the report users.
- Secondly, you want to prevent internal duplication of information/reports. A precondition of BI is to understand the data you are working with and to know which former reports were made. You don’t want to duplicate existing reports or start on a new dataset that has already been set up by a colleague.
- Thirdly, a good documentation will avoid inconsistencies regarding definitions or misinterpretations of visualizations.
The issues mentioned above can be solved by offering the right documentation to the right people. Do note that it is not necessary to lose too much time on the small details, but concise documentation of the important elements will certainly improve internal operations.
What should you document?
When talking about a BI reporting project, things like the planning, the roles, the scope or the requirements of the project should of course be documented. However, for this article we want to focus on the documentation of the BI report itself. Understanding and outlining the flow of the source data to its final destinations is a big challenge, but it can be tackled by taking the following elements into account:
First, it’s important to realize that the source data itself comes with a lot of extra information. A colleague should know about the transformation from the source data to the data used for the report (ETL), the history, the anomalies and probably even the recent updates. Besides that, documentation of the underlying data model is necessary, even a brief description of the relationships and assumptions can help to offer the right insights. Finally, the visualizations themselves cannot be forgotten. Definitions of the measures used (DAX), what the table presents, the KPIs, and even certain concepts (columns) are noteworthy elements.
How should you document?
(Examples for Power BI)
To document you could use documents in Word or Excel. Maybe there are internal information sharing platforms inside your company that you use to gather all the documentation. Many companies still work with these tools, however, there are other solutions to make documentation a lot easier. With the simple push of a button these tools produce a preformatted document with information on your report. You can then enhance this document further as you like.
There are a lot of business intelligence tools. Think of Tableau, Power Bi, QlikSense, SAS Analytics, SAP Business Intelligence, Oracle BI, Sisense, etc. All these tools have other tools/extensions that allow you to document. Since discussing every tool is a bit too broad, our focus will be on Power BI and its documentation tools/extensions.
For very basic documentation, Power BI itself already offers the possibility to add descriptions to measures, tables, columns, and other functions in the properties frame (as you can see to the left). You can also add comments in the (DAX or power query) code itself.
Yet, for further documentation and clearer summaries there are some useful automated tools/extensions: DAX Studio, Tabular editor, Power BI Cleaner, Power BI Sentinel, Power BI Assistant, Power BI Documenter V2, Data Vizioner, etc. Some developers also prefer to use external platforms such as Whatfix or Github to generate the documentation of their BI reports.
Tools such as the Power BI Documenter V2 automatically generate a document with information regarding the tables, the columns, the measures, the relationships, and the security. Each tool focuses on specific aspects and has its own values. Functionalities is certainly one aspect that should be taken into consideration when choosing a tool to document your Power BI reports. However, there are other aspects that will influence your decision. We list the most important ones here:
- Functionalities (as already mentioned before): What can this tool do for me? In what format does it offer this documentation to me?
- Pricing: How much would it cost me to implement this tool into our organization?
- Transferability: How easily can a colleague get access to this documentation?
- Maturity of the tool: Is the tool still in development? Or does it already exist for a couple of years?
- Ease of use: How straightforward is it to use this tool?
When choosing the right tool, you have to keep in mind that “perfection” doesn’t exist and what seems like the best tool for one company can be completely useless for another.
We suggest using a tool that is free/low cost, easily transferable and easy to use. We don’t regard maturity as crucial, the tool either has most of the functionalities you need, or it doesn’t. How long it has been around shouldn’t enter the equation. And as said, there will never be a tool that covers your needs 100%, unless you develop in house, which we certainly see as unnecessary.
 Self-service BI = the concept of handing tools to business experts (like marketing or sales managers) that gives them the ability to find data, analyse data and build reports themselves without the help of IT professionals or data analysts.