Love & Hate: documenting Power BI
Dennis Priester
Mad Scientist | Data and Visualisation Expert | Building insightful Excel and Power BI solutions since 2008
Documenting your creations properly is something that is often overlooked, as there is always something that has priority over it. Most will have a love & hate relationship with this activity called documenting: you know it is something you should do, but in the end answering requests to change or create new reports is simply much more fun. On top of that, for the running business of your customer, proper documentation often has no priority at all: it is much more important to get this critical business insight and pretty please do it as soon as possible. Oh and p.s. : we do not really have additional budget for documentation.
That said: I do think documenting Power BI is important. But I am searching for an answer on how to do it in a balanced way. With BI as a self service platform you should not want to go into classic time-consuming document-it-all mode, but only capture and cover the essence of the report to make it sustainable and maintainable.
Insights from the business
In my search for an answer, I asked some experienced ICT managers within the businesses that I work for what they thought a proper Power BI documentation should at least consist of. This resulted in the following 6 points:
- Why: Why do we want the report? What do we want to achieve with the Power BI Report and what is the purpose of the report and the purpose of the individual pages within
- What: What are the business requirements. What should be shown, what filters, time ranges, what data fields
- Where: Where does the data come from? What is the update frequency? What ETL steps are in place prior to loading in BI?
- Who: Who should have access to the data, the report, the apps. Is there a user-based data restriction? Who owns the report and the process? Who is responsible for user access?
- How: How to handle the reports? Is there a specific story line to follow? Are there certain user scenario's in place?
- External documentation on code etc is not needed unless very specific / contains hard coded items - this creates unnecessary overhead.
In my opinion, points 1, 2 and 4 are completely business driven and should not be the responsibility of the developer to document. Point 3 can be done in collaboration with the ICT department of a customer. Point 5 is a combined effort. Of course I realize that this is quite black and white - in reality you often work together with the customer towards a report that perfectly fits their organisation. In it's basis though - these points seem very legit.
Technical documentation
Although point 6 is perfectly valid, I do recognize that proper in-document documentation is important although most will agree it is not a developers favorite way to spend their time. I came up with the following additional basic rules for proper in-document documentation:
- Field description: Measures and (calculated) columns should be given a description so that it’s purpose is immediately clear. You can do this by right-clicking the field and selecting 'properties'
- DAX Formatting: DAX should be formatted according to the 'unofficial' DAX formatting standard. You can easily do this at the daxformatter site. This greatly helps you read and understand code. Link is given in the comment.
- DAX commenting: please comment where needed. Keep in mind here: the fact that you do not need it now to understand your code does not mean that you or someone else does not need it later. I cannot count the occasions that I first had to think on how I meant something in the first place
- Clear query steps: Query editor steps need to be given logical names in case the purpose is not directly clear. Also, they need to be given a property description. A nice video about this practice is given by Reid (see below video) which is similar to the practice of point 1.
- M-code commenting: M-code customized in advanced editor needs to be commented where needed. Keep in mind the comment on point 3.
- RLS: The ideas and working principle behind any (dynamic) RLS should be described properly. Keep in mind also the formatting and commenting here.
- Purpose of bookmarks: The idea behind bookmarks should be documented as for a developer it might be hard to see exactly what visuals are affected using a bookmark. Therefore a description with the purpose of each bookmark is quite useful. Please keep it readable though; say 'bookmark toggles the visibility from actual sales to last year sales' rather than 'the visual filter on the field 'year' on the chart visual named barchart_sales is changed from [currentyear] to [currentyear-1]'
- Model relation: In case you use relations in your BI data model, explain where needed. If you prefer include a printscreen of the model itself.
To conclude
The above points, originating both from the business and from my own experience should construct a pretty stable basis for a proper documentation. However I also realize that this is just my interpretation and therefore I would like to invite you to contribute into this discussion.
Do you have any recommendations, remarks or suggestions? Please let me know
Example on formatting/commenting
Reid Havens video on query step properties
Data Analyst at ABN AMRO Bank N.V.
6 年That's an excellent discussion topic! I have to say this is the first article on the topic I read - and I read a lot about Power BI.? There are a few things I'd like to add to your already excellent list - first is 'where does the documentation takes place' - as it is often the case with large organizations, a report would change hands many times in terms of ownership and it's purpose can get easily lost along the way. It will be stored initially on a local machine, then on a shared drive, then on a SharePoint and perhaps on a OneDrive - so in my opinion, having documentation that is NOT in-document (on a hidden page) is bound to be lost.? The second & third point are about the 'change log'. The 'owners' would almost always vary in terms of Power BI skills and business knowledge and, what is worse, in what their ownership of the report constitutes. Some will own the report for a few years and others - for a few weeks as an interim. Some will know the bits and pieces and others will know just how to switch the source. So, there should be some distinction as to what the roles related to the report are and what comes with the ownership of the report. In brief - the report documentation should have an up-to-date RASCI matrix. Third, changes to the report would be also different in their purpose and magnitude- some changes will be minor and cosmetic, and other will be significant, such as source change or even intent. While there must be a balance between information clarity and overhead and not every change has to be documented, small things like 'who requested this change' may turn out to be vital in the long run and save dozens of hours of meetings.
Power BI Developer
6 年Really good article. I'm now feeling guilty and so will go back and document my current project properly....
Consultant PowerBI chez Capgemini
6 年Adrien Lefevre?:)
Chief Digital Health Officer
6 年Luke Garton