Data TutorialsDashboards

How to Create Documentation for Dashboards

Posted by Tracy Chow

There are situations where a user is viewing a dashboard and doesn’t know what the charts and metrics on the dashboard represent. This really slows down the user, who is trying to interact with the dashboard and interpret the data.

In order to provide some context and guidance to the viewers of your dashboard, it’s a good idea to create documentation surrounding your dashboard. In this tutorial, we’ll look at aspects of your dashboard that you will want to include in your documentation.

Dashboard Description

Every dashboard should have a summary or short description of what the dashboard is intended to show and who the intended audience is. Does the dashboard show a historical monthly view of KPIs intended for organizational management review, or does it contain more detailed data of activity meant for regular use by an operational team in the sales department?

It may also be helpful to provide possible use cases and examples of insights users can get out of the dashboard. For example, a dashboard can be primarily meant for monitoring at the weekly company all-hands meeting, with charts indicating how close or far teams are to meeting their monthly objectives.

Dashboard Settings

A dashboard is only as useful as the quality of data it provides to the users and viewers. Therefore, it is important to include in your documentation where the data is coming from, how often the data is refreshed, and what filters are applied.

For example, you can state your dashboard is querying Salesforce data from the main Amazon Redshift data source, and that the dashboard is refreshed every hour. If there are filters applied to the dashboard as a whole, those should be mentioned as well. For instance, stating that the user metrics shown on the dashboard are only the users whose status is “active” or “trialing”.

Chart Descriptions

Going along with information on the dashboard settings and applied filters, dashboard documentation should contain descriptions of the charts and the interactions between them. Is there a dropdown or calendar filter viewers can interact with to filter the data? Which charts are the interactive filters going to affect?

In addition, each chart on the dashboard may be showing the data in unique ways. How is the data aggregated or calculated? What are the charts supposed to show, and what kinds of insights can the user glean from the charts? If the data in the chart is trending up or down, what does that imply? Cite a specific chart by its chart title so readers know exactly which chart is being referred to.

Metric Definitions

If there are metrics or KPIs on your dashboard, explaining how each metric is defined will help the viewer understand what the numbers indicate. What formula is used to calculate each metric, and should it be compared to a goal or target value? How was the goal decided, and how often is the goal reestablished if applicable?

Owner Information

It is also best practice to cite the owner and contributors of the dashboard. Who is the owner of the dashboard, and how can he or she be contacted if someone has questions about the data or requests changes on the dashboard?

Change Control History

Last but not least, it’s handy to keep a log of when the dashboard was edited and what changes were made. This helps the viewer know if there were any changes made to the dashboard since they last viewed it. Perhaps a metric was redefined, or a chart was removed. Keeping a log of changes will remove any ambiguity and put everyone on the same page.


Dashboard documentation is important to provide context to viewers, and including key components into your documentation will help ensure the user has the necessary information to understand and interpret the data.