Have you ever been asked to update a dashboard you didn’t create? Or develop a dashboard for someone else who must maintain it? How about having a dashboard break months down the line and struggling to figure out where to start troubleshooting? In these scenarios, a well-documented dashboard would be a gift.
Below are recommended best practices for properly documenting a dashboard.
Tableau Desktop
Requirements
- Clean requirements are essential for a dashboard. Have a centralized place to store requirements.
- To assist Creators, OTDI has created a Requirements Gathering Template, KPI definitions requirements, and outlined how these are part of the Dashboard Development Lifecycle (DDLC).
Comments
- Add comments to dimensions or measures
- Your data source field names may be unclear or have a specific meaning unique to the data source. Trying to decipher why a field is named a specific way, can take time. Adding comments clarifies those fields. It will also appear in the lineage of data sources. Right click on a dimension or measure, select ‘Default Properties’ then select ‘Comment’.
- Create a comment in a calculated field
- When creating a field, add “//” to each line of text; if the comment requires multiple lines of text, use “/*” at the beginning and end of the comment. This will help your future self and other developers know why a calculated field was created or what it does.
Organization
- By default, Tableau groups fields by data source. To change this, select “Group by Folder”. Folders may be organized by all fields on one dashboard or similar calculations, such as all date logic.
Calculated fields
- Apply standard prefixes to calculations. For example, CY or CFY for current fiscal year; PY or PFY for previous fiscal year. Other prefix ideas include diff for calculations that show differences or dte for date calculations.
Miscellaneous
- Color code tabs based on purpose. Tab colors do not appear to end users on Server.
- Create a dashboard change log for when multiple developers are on a project. Developers should use a text object to date and describe changes made.
- Leverage AI to document your code. Ideas on how to use AI and which AI tool to use are available.
- These two short tips show you how to view the metadata behind a dashboard and add notes or documentation to a dashboard.
Tableau Prep
Comments
- Add comments to key steps. This helps others understand transformations and keeps your workflow organized. Comments are limited to 200 characters. This short video shows how to add comments.
Tableau Server
Descriptions & Lineage
- Leverage descriptions to provide end users and analysts information about workbooks and data sources. Both a template for descriptions and a step-by-step guide on adding descriptions is available.
- Lineage allows anyone to trace the source of the data; you may also add descriptions for documentation purposes for yourself or others. These descriptions will appear in the Data Guide within Tableau Server and if desired, flow to Ohio State’s data catalog. A short video on how to add lineage is available.