Descriptions are an underutilized feature in Tableau Server and Tableau Cloud. Many objects on the server can have a description, such as projects (basically folders to organize content), data sources, and workbooks. The issue is that descriptions aren’t usually standardized and can be haphazard — showing up as a minimalist note on one object, too robust on another, and completely missing from most. What you really want is a description that is concise, clear, and consistent. It needs to provide helpful information, without being overly wordy. And if it has a consistent format across similar objects, it becomes really easy to compare different objects to find the appropriate one.
But, descriptions can be difficult to write. It is a burden to articulate the relevant information in just a few sentences. And what is relevant to one person might not be relevant to someone else. Key pieces of information could be left out or it could become too long. That’s why, most of the time, people don’t write anything in that description box.
To make the use of descriptions easy for all, it is best to have a template — a few short sentences that provide the foundation for capturing the necessary information, with blanks for creators to fill in based on their object. A template ensures the right details are being documented, that the descriptions follow a given standard, and that it isn’t a burden for a creator to use. Let’s dive in and talk about what should be included in a template.
Project Descriptions
Things to Consider
- How are projects used in your organization?
- What is the purpose of the project?
- Is it used to grant access, simply organize, or both?
- Are the contents meant for a specific audience or are they about a certain topic?
- Who has access to the project?
- How is access granted?
- What types of content belong in the project?
- Who creates objects for this project?
Sample Template
This project contains information pertaining to _____ and is intended for use by _____. This project is secured by the _____ group.
Data Source Descriptions
Things to Consider
- What is the underlying system or source of the data?
- Is it joined with other data?
- Have any transformations been performed?
- Have any filters been applied?
- What is the level of granularity? What does each record represent?
- When is the data available?
- Who has access to the data?
- How is access granted?
- If there are questions, who is the subject matter expert?
Sample Template
This data is sourced from _____ and is joined with _____. Each record represents _____. It is updated on a _____ basis. For questions, please reach out to _____.
Workbook Descriptions
Things to Consider
- What is the purpose of the workbook?
- What questions does the content attempt to answer?
- How should users utilize the content?
- Who should use the workbook?
- Are there any caveats when using the views?
- Have any filters been applied across the entire workbook?
- If data sources are embedded in the workbook, consider all the elements from the data source section above.
Sample Template
This workbook was developed to answer questions about _____ and is intended for use by _____. For questions, please reach out to _____.
From Underutilized to Utilized
Based on the answers to the prompts above, your templates may need to be different. Please customize them as needed to capture the information you deem necessary. Keep them in an easy-to-find place and encourage everyone to use them. Also, know that descriptions will need to be modified on a case-by-case basis, even if you have a template. Templates are meant to be a helpful guide and not a rigid construct.
Now, let me show you where these descriptions can be found.
Projects
Data Sources
Workbooks
Bonus tip: descriptions are searchable within Tableau Server and/or Tableau Cloud, so they are a great way to make it even easier for users to find your content.
What are you waiting for?!
A few minor edits:
- The screenshots above are what you see when navigating in Tableau Server or Tableau Cloud.
- When creating a project on the server, or when publishing a data source or workbook, you will have the option to include a description. That's where you should use your template!
- Individual fields in a data source can also have a description, though those are harder to templatize. You can read about those on my recent post 12 Enterprise Tips & Best Practices for Tableau.
- Make sure you subscribe to hear about the next part in this series and other Tableau things.
