Documentation and naming conventions in Tableau - Real Business Scenario

Scenario Mode

👤 Your Role: You are a Tableau developer at a retail company.

📋 Request: Your manager wants you to create a clear and easy-to-understand sales dashboard. They also want you to follow good documentation and naming rules so others can easily use and update your work.

📊 Data: You have monthly sales data by region and product category. The data includes columns for Date, Region, Product Category, Sales Amount, and Quantity Sold.

🎯 Deliverable: A Tableau dashboard with clear names for sheets, fields, and calculations, plus documentation explaining your naming choices and how to use the dashboard.

Sample Data

Date	Region	Product Category	Sales Amount	Quantity Sold
2024-01-01	North	Electronics	12000	30
2024-01-01	South	Furniture	8000	15
2024-02-01	East	Electronics	15000	40
2024-02-01	West	Furniture	7000	10
2024-03-01	North	Clothing	5000	50
2024-03-01	South	Electronics	11000	25
2024-04-01	East	Clothing	6000	60
2024-04-01	West	Electronics	13000	35

1

Step 1: Rename data fields with clear, descriptive names in Tableau's Data Pane.

Rename 'Sales Amount' to 'Total Sales USD', 'Quantity Sold' to 'Units Sold', 'Product Category' to 'Category', 'Date' to 'Sale Date'.

Expected Result

Fields have clear, consistent names that anyone can understand.

2

Step 2: Create calculated fields with meaningful names and add descriptions.

Create 'Average Sales per Unit' with formula: [Total Sales USD] / [Units Sold]. Add description: 'Average sales value for each unit sold'.

Expected Result

Calculated field named 'Average Sales per Unit' appears with description for easy understanding.

3

Step 3: Name worksheets clearly to reflect their content.

Rename sheets as 'Monthly Sales Trend', 'Sales by Region', and 'Category Performance'.

Expected Result

Worksheet tabs have clear names that describe the visualizations.

4

Step 4: Add dashboard and worksheet captions to explain purpose and usage.

Add caption to 'Monthly Sales Trend' sheet: 'Shows total sales each month across all regions.' Add dashboard caption: 'This dashboard helps track sales performance by time, region, and category.'

Expected Result

Captions appear below sheets and dashboard, guiding users.

5

Step 5: Use consistent naming conventions: capitalize first letters, avoid abbreviations, and separate words with spaces.

Ensure all field and sheet names follow this style, e.g., 'Total Sales USD' not 'totalsalesusd' or 'TSUSD'.

Expected Result

All names are easy to read and consistent throughout the workbook.

6

Step 6: Document your naming conventions and dashboard usage in a separate Tableau Story or a text box on the dashboard.

Create a Story page titled 'Documentation' explaining naming rules and how to use the dashboard filters and views.

Expected Result

Users can read the documentation to understand the dashboard and naming rules.

Final Result

Monthly Sales Trend

↓

Sales by Region

↓

Category Performance

✓Sales vary by month with a peak in February.

✓East region shows strong sales in Electronics.

✓Clothing category has steady sales across regions.

✓Clear naming and documentation make dashboard easy to use and update.

Bonus Challenge

Create a parameter to allow users to switch between viewing sales by 'Region' or by 'Category' in the same chart.

Show Hint

Use a parameter with values 'Region' and 'Category' and a calculated field that returns the selected dimension for the chart.

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