Laura Learns Data

Revisiting an old topic with fresh eyes. One of the first blogs I ever wrote was about Documenting your Tableau Workbook back in 2017. I explored different techniques to document your dashboard, in this blog I am going to evaluate my recommendations and see if they are still best practice.

Why Document your Tableau Workbooks?

When I first wrote about this I was primarily concerned with Knowledge Sharing, enabling others to understand your work without needing to decipher every detail. That is still a valid reason, but there are a few more:

• Clarity and Transparency: Clearly explain the purpose, data sources and logic behind your work.
• Ease of Maintenance: Simplify updates and troubleshooting by providing context. You are writing notes for future you, who hasn’t looked at this project in months.
• Reusability: Facilitate the reuse of sheets, calculations, and data models in future work.

Key Elements of Effective Tableau Workbook Documentation

My original blog post only really touched on documenting calculated fields. Now after many years working in BI I know that there are a lot more elements we should be keeping track of.

1. Workbook Overview – Describe the purpose of the workbook. Summarize the key questions it addresses
2. Data Sources and Connections – Detail the data sources used and any refresh schedules and dependencies
3. Data Model and Structure – Explain the relationships, joins and unions.
4. Calculations and Logic – Provide explanations for complex field calculations
5. Dashboard Sheet Descriptions – Highlight interactive elements and how they are meant to work
6. Version Control and Change Log – Keep track of updates fixes and enchancements
7. Additional Tips – Useful information for future troubleshooting

Best Practices for Documenting in Tableau

My original post on using Tableau’s built in functionality, like Descriptions, Comments, and Captions as demonstrated in this Tableau Dashboard.

var divElement = document.getElementById(“viz1719599271466”); var vizElement = divElement.getElementsByTagName(“object”)[0]; vizElement.style.width = “100%”; vizElement.style.height = (divElement.offsetWidth * 0.75) + “px”; var scriptElement = document.createElement(“script”); scriptElement.src = “https://public.tableau.com/javascripts/api/viz_v1.js”; vizElement.parentNode.insertBefore(scriptElement, vizElement); var divElement = document.getElementById(“viz1719599271466”); var vizElement = divElement.getElementsByTagName(“object”)[0]; vizElement.style.width = “100%”; vizElement.style.height = (divElement.offsetWidth * 0.75) + “px”; var scriptElement = document.createElement(“script”); scriptElement.src = “https://public.tableau.com/javascripts/api/viz_v1.js”; vizElement.parentNode.insertBefore(scriptElement, vizElement);

I now also see the value in Eternal Documentation, like maintaining supplementary documents or wikis for more comprehensive details.

Final Thoughts

Documentation is a critical yet often overlooked aspect of data storytelling. By investing a little time upfront, you can save hours down the line – making your Tableau Workbooks more accessible, understandable and maintainable for everyone involved.