Do you usually document the reports you develop? I do, and today I want to show you how I approach it from a technical standpoint, keeping in mind other team members (colleagues, clients, or anyone who wants to audit your work) who may need to interact with or continue your work in the future.
I enjoy creating my own standards and using them as a guide for both myself and my teams. I believe that they are a crucial channel of communication and productivity.
Before continuing, I want to clarify:
First, I will refer to "Controls" to talk about objects in a report: a table, a graph, a text, and so on.
Second, I will not discuss the vision of functional documentation. Instead, I will focus on the technical perspective.
Third, I always name the controls in English because it’s more ‘universal’ and has better abbreviations (in my humble opinion).
Syntax
I aim to keep my character count under 25 to avoid expanding the selection panel width too much, which would reduce my canvas size.
The simplest option:
PrefixControl + '_' + Name
e.g. -> shp_background Related controls:
PrefixControl + '_' + PrefixRelatedControl + '_' + Name
e.g. -> shp_card_back (abbreviation of background)Considering subtypes:
PrefixControl + '_' + subType + '_' + Name
e.g. -> txt_H1_Page (H1 = main title of the page)Abbreviations or prefixes for controls:
I got these ideas from programming mainly (c#, css, etcetera)
btn: Button.
lbl: Label (Quienes indican al usuario qué dato corresponde en cada field.
tip: Tooltip (n tooltip es un elemento de interfaz de usuario que se utiliza comúnmente en sitios web y plataformas para mejorar el recorrido del usuario y guiarlo hacia donde debe ir.
txt: Textbox: titles, comments, etcetera.
sel or Filt: Selector or Slicer or Filter. If you want to be more detailed (not me in this case), you could use the following:
ddl: Lista desplegable (Dropdownlist)
ckl: CheckedListBox
cdr: Calendar, date slicer.
tbl: Table.
mtx: Matrix.
pic: Pincture or Image.
icn: Icon.
card: es común utilizar la abreviatura "card" para referirse a un componente o elemento visual denominado "tarjeta".
shp: Shapes (Rectangle, Rounded Rectangle, etcetera).
menu: Menu.
app: Application, embed a Power Apps visual in a Power BI report.
map: Map.
Exception: If controls have a configured title, by default the text described as the title appears as the name of the control, which I do not really like.
Underscore ‘_’
I use the "_" (underscore) symbol a lot to replace spaces. IMHO it makes the code cleaner, easier to read considering the syntax, more convenient to write code (Using PBIP, you can read code and work with it) and I like it.
Name
Please use a descriptive Name, but keep it concise. Remember to limit the number of characters, as discussed earlier.
Conclusions
I had been iterating the way to document reports as a developer from a technical perspective for some time and I found inspiration in programming standard documentation. Then, I wrote my list based on software techniques, and my own experience and judgment. Finally, I started to implement it.
No matter how you implement the documentation technique, create your ‘style’ and just use it.
Thinking about productivity: know where the controls are located and their order, and be able to access them quickly through the view. A documented code makes it easy to read and easy to find controls when you have to create report interactions (and more). Be smart and agile. 😎
Standardizing your way of documenting facilitates teamwork, inheritance of the code and auditability of DataViz process, your work indeed.
This is for the good of humanity, you, your team and the client, be kind, everybody will be happy. 😊
I would like to receive your comments, ideas or related practices to share and work better. And if this post has helped you, it makes me happy. 😁
📢 Spoiler alert: I'm writing a set of posts related to documentation focused on Power BI team members, including developers, functional experts, project managers, and end-users. The posts will cover self-service strategies and consider different perspectives and components of Power BI projects. Stay tuned!
Cheers 🤟
Matías