Model for Data Content - Dashboards, tables, and visuals

This is a model for a Mass.gov page that features a dashboard or data visualization. Use the model to guide your own data content publishing.

This model demonstrates how MA government organizations should design pages that feature dashboards, tables, and visualizations (maps, graphs, charts, etc.). It provides both a structure you should follow and best practices on each page element.If you have questions, please contact the Massachusetts Data Office by scheduling office hours.

Title: The title should summarize the purpose of the page as succinctly as possible using words your audience will know. It should be unique among Mass.gov pages. Keep in mind that most people find your content from search engines. They might see this page’s title without visiting your other pages. 

Subheader (or “Short Description” in the CMS): Short descriptions should complement titles. If a title summarizes what’s on the page, a short description provides more description of what the page is for and what you can use it to do. Keep them to 1-2 sentences.

Table of contents: A table of contents will automatically appear if there are 3 or more sections on your page. 

Overview

This section demonstrates the overview you should create to summarize the purpose of your visualization(s). It should  provide critical context that readers need to understand the data, including

• A description of your data 
• Publishing organization(s) 
• When the data was last updated and the general cadence of updates you publish 
• Why the data was collected 

There may be other important context to provide, too. This model dedicates space below your dashboard or table to an "About the data" section, where you can provide more information for users.

Please note, although there is a dedicated section within the CMS for an overview, you need to create your own (the way this model does) by adding a new heading and section content. This will allow you to organize the page so the overview of the dashboard is after the table of contents.

Adding contact information to your data content

Use the contact information template to provide an email for users to get in touch with your data owners. Note that on this Mass.gov content type, you'll find contact information both at the bottom and in the top right.

You may need to create a new contact information template that differs from the normal one you provide on non-data pages. Once created, you can insert it onto any page that contains data. It is possible to include both sets of contact information if you need to. 

We strongly recommend that questions about data go to a shared mailbox (e.g. [e-mail]) rather than a specific person’s email. That way, if your data owner moves to a different role or organization, you don’t need to update your web content. Alternatively, your organization needs to be vigilant about updating contact information when your staffing changes. Either way, you or someone on your team should be accountable for receiving and responding to user feedback and questions. 

The dashboard, table, or visualization

CMS tools you can use to embed your dashboard

Embed an iframe

An iframe allows you to embed one web page in another. For example, if you create and publish a dashboard using Power BI, you could then embed that Power BI dashboard on Mass.gov. 

Note: Refrain from using images of data to substitute for an interactive dashboard. Dashboards in PDFs or image files are much less accessible than visualizations created in business intelligence (BI) software. If you don't have the capacity to create a dashboard using a BI tool, post the data as a csv (or other machine readable format).

Tableau Visualization

If your agency uses Tableau to create dashboards, you should use the "Tableau Visualization" embed option. This tool includes special features that help with sizing and user functionality.

Here's an example of a visualization that uses the Tableau Visualization tool.

Skip this  data visualization presentation.

You skipped the data visualization presentation.

This is a caption that you can include below your dashboard. It can contain guidance for users, call out key takeaways, and link to a file so users can download your dataset.

Searchable CSV table

CSV tables allow you to display tabular data that can be filtered and sorted. It also includes pagination and automatically adjusts to visitors' screen sizes so that there is never any horizontal scrolling. To create one, you'll just need to upload a CSV. Below is an example of a CSV table with mock data.

Example of a searchable CSV table (mock data)

MOCK_DATA_0.csv

Table contains mock data.

Creating accessible, usable dashboards & visualizations

Any dashboards or visualizations you publish must be usable and accessible. You should be thinking usability and accessibility in your earliest design phases, not when you're just about to publish. 

Here are some resources you can use as you design your dashboards:

• Data office data visualization design guide
• Tool for checking color contrast
• Tableau: accessibility documentation
• Power BI: accessibility documentation
• Tableau: creating dashboards for different device sizes
• PowerBI: creating dashboards for different device sizes

About the data

You should include a section like this one to provide more details about your data. Describing key takeaways, data collection methods, and limitations and gaps in the data will help users in understanding the data and how the data may be used.

Data dictionary

Your data content should include a data dictionary that lists the meaning and types of data in each field. You can do this in HTML, in a downloadable file, or both.

A good data dictionary includes plain language definitions of each variable, dimension or metric. Here's an excerpt from a data story on youth arrests.

Definitions:

Calendar year: Always refers to a period of January 1 through December 31 of the same year

Diversion: Any program that allows youth who commit an offense to be directed away from more formal juvenile justice system involvement. In the context of youth arrests, diversion means giving a youth a warning or referring them to a program rather than making an arrest or issuing a court summons. 

Felony: Any serious crime which, if committed by an adult, could be punished by incarceration in state prison.

Fiscal year: Always refers to a period of July 1 through June 30 of the same year.

Gender: The National Incident Based Reporting System (NIBRS) reports with the following options: Male or Female. Data collection for gender is officer-observed.

Additional information to include about your data

Consider including any of the following sections if they are relevant:

• Provide a detailed summary of the dataset (that is, elaborate on your overview) 
• State summary metrics and major takeaways 
• Call out the most important variables or dimensions in the dataset 
• State the limitations of the data 

Supplemental downloads

Provide a downloadable version of your data alongside your dashboard. You can do this in the Additional Resources field at the the bottom of your "About the data" section, or you can do what we've done here so that you can provide descriptions of your files.

Download: My agency's dataset (2015-2021) (xlsx)

• This file contains the raw data used in the dashboard.

Download: Data Dictionary (xlsx)

• Metadata about the dataset, including definitions, data type, column constraints, and nullability.