Documentation and naming conventions in Tableau - Dashboard Guide

Dashboard Mode - Documentation and naming conventions

Dashboard Goal

This dashboard helps you understand how to organize and document your Tableau workbooks clearly. It shows examples of good naming and documentation practices so your reports are easy to read and maintain.

Sample Data

Order ID	Region	Sales Person	Sales Amount	Order Date
1001	East	Alice	250	2024-01-15
1002	West	Bob	400	2024-01-20
1003	East	Charlie	150	2024-02-05
1004	South	Alice	300	2024-02-10
1005	West	Bob	500	2024-02-15

Dashboard Components

• KPI Card: Total Sales
  Formula: SUM([Sales Amount])
  Result: 1600
  Description: Shows total sales amount from all orders.
• Bar Chart: Sales by Region
  Formula: SUM([Sales Amount]) grouped by [Region]
  Result: East=400, West=900, South=300
  Description: Visualizes sales distribution by region.
• Table: Sales Person Performance
  Columns: Sales Person, Total Sales
  Formula: SUM([Sales Amount]) grouped by [Sales Person]
  Result: Alice=550, Bob=900, Charlie=150
  Description: Lists total sales per sales person.
• Documentation Text Box
  Content: Explains naming conventions used:
  • Fields named with clear, descriptive names (e.g., Sales Amount not Amt)
  • Calculated fields named with prefix Calc_ (e.g., Calc_TotalSales)
  • Dashboards and sheets named by purpose (e.g., Sales Overview)

Dashboard Layout

+----------------------+---------------------+
|      KPI Card        | Documentation Text  |
|   Total Sales: 1600  |  Naming Conventions |
+----------------------+---------------------+
|          Bar Chart: Sales by Region           |
|  East:400  West:900  South:300                |
+-----------------------------------------------+
|       Table: Sales Person Performance          |
| Alice:550  Bob:900  Charlie:150                |
+-----------------------------------------------+

Interactivity

Adding a filter for Region will update the KPI card, bar chart, and sales person table to show data only for the selected region(s). The documentation text remains static as it explains naming rules.

Self Check

If you add a filter for Region = West, which components update and what are their new values?

• KPI Card: Updates to total sales for West = 900
• Bar Chart: Shows only West region bar with value 900
• Sales Person Table: Shows Bob with 900 sales only
• Documentation Text: Does not change

Key Result

A simple Tableau dashboard demonstrating clear documentation and naming conventions with sales KPIs and visuals.

Practice

1. Why is it important to use clear and consistent naming conventions in Tableau?

easy

A. It makes Tableau run faster.

B. It helps users understand and maintain dashboards easily.

C. It automatically creates visualizations.

D. It reduces the file size of Tableau workbooks.

Solution

1. Step 1: Understand the purpose of naming conventions

   Clear and consistent names help users quickly understand what each field or dashboard represents.

2. Step 2: Connect naming to maintenance

   When names are clear, it is easier to update or fix dashboards later without confusion.

3. Final Answer:

   It helps users understand and maintain dashboards easily. -> Option B

4. Quick Check:

   Clear naming = easier understanding and maintenance [OK]

Hint: Clear names make dashboards easy to read and update [OK]

Common Mistakes:

• Thinking naming affects performance
• Assuming Tableau auto-documents everything
• Ignoring the importance of maintenance

2. Which of the following is the best practice for naming a calculated field in Tableau?

easy

A. Use descriptive names like Total Sales 2023.

B. Use vague names like Calc1 or FieldX.

C. Use special characters like Total$Sales!.

D. Use very long names with unnecessary details.

Solution

1. Step 1: Identify clear and descriptive naming

   Descriptive names explain what the field calculates, making it easier to understand.

2. Step 2: Avoid vague or confusing names

   Names like Calc1 or special characters can confuse users and cause errors.

3. Final Answer:

   Use descriptive names like Total Sales 2023. -> Option A

4. Quick Check:

   Descriptive names improve clarity [OK]

Hint: Name fields clearly to describe their purpose [OK]

Common Mistakes:

• Using generic names like Calc1
• Including special characters that cause errors
• Making names too long and confusing

3. Given a Tableau calculated field named Profit Margin with the formula [Profit] / [Sales], what would be the best description to add in the documentation?

medium

A. "Calculates the ratio of profit to sales as a percentage."

B. "Counts the number of sales transactions."

C. "Shows total sales amount."

D. "Filters data by profit values."

Solution

1. Step 1: Understand the formula meaning

   The formula divides profit by sales, which calculates profit margin as a ratio.

2. Step 2: Match description to calculation

   The description should explain this ratio clearly, not unrelated actions like counting or filtering.

3. Final Answer:

   "Calculates the ratio of profit to sales as a percentage." -> Option A

4. Quick Check:

   Description matches calculation purpose [OK]

Hint: Match description to what the formula actually does [OK]

Common Mistakes:

• Confusing calculation with counting or filtering
• Writing vague or unrelated descriptions
• Ignoring the formula's actual logic

4. You see a Tableau dashboard with field names like Fld1, Fld2, and no comments or descriptions. What is the main problem here?

medium

A. The dashboard uses too many colors.

B. The dashboard will not load in Tableau.

C. The dashboard will show incorrect data.

D. The dashboard is hard to understand and maintain.

Solution

1. Step 1: Identify the impact of poor naming

   Names like Fld1 are vague and do not explain what data they hold.

2. Step 2: Understand the effect of missing documentation

   Without comments or descriptions, users cannot easily understand or update the dashboard.

3. Final Answer:

   The dashboard is hard to understand and maintain. -> Option D

4. Quick Check:

   Vague names + no docs = poor usability [OK]

Hint: Vague names cause confusion and maintenance issues [OK]

Common Mistakes:

• Assuming dashboard won't load due to naming
• Thinking data will be incorrect without comments
• Focusing on colors instead of naming issues

5. You are creating a Tableau project for sales analysis. Which combination of documentation and naming conventions will best help your team collaborate and maintain the project?

hard

A. Use special characters in names; write long paragraphs in descriptions; skip comments.

B. Use short random names; avoid descriptions; rely on memory for dashboard logic.

C. Use clear, consistent field names; add descriptions to calculated fields; comment dashboards.

D. Name fields with numbers only; add no descriptions; use colors to explain logic.

Solution

1. Step 1: Identify best naming practices

   Clear and consistent names help everyone understand the data fields easily.

2. Step 2: Recognize importance of documentation

   Descriptions and comments explain calculations and dashboard logic, aiding collaboration and maintenance.

3. Step 3: Eliminate poor practices

   Random names, missing descriptions, or relying on colors alone cause confusion and errors.

4. Final Answer:

   Use clear, consistent field names; add descriptions to calculated fields; comment dashboards. -> Option C

5. Quick Check:

   Clear names + docs = better teamwork [OK]

Hint: Combine clear names with comments and descriptions [OK]

Common Mistakes:

• Skipping documentation assuming names are enough
• Using unclear or random field names
• Relying on colors instead of text explanations