Guides

Use for an overview of a complicated process or service.

Summary

Guides offer an overview of a complicated process or service. They’re especially useful if the process involves multiple organizations. Examples of Guides include:

Or even…

Important: Guides are not good content types for lists or directories.

Guides have been designed for content that can be broken into steps, or that’s interrelated. If you need to make a list or directory, use a Curated List.

To save a draft of your Guide, you’ll need to author/add:

  • Title

  • Guide intro

  • Header image

  • At least one section

Though it’s not required, we recommend you include Key actions wherever possible.

The best places to link Guides are:

  • Under the First time guide section on Service Pages

  • Under the What you need to know section on Service Pages

  • In Related links sections on appropriate pages

If you’re using a Guide because you’re struggling with long-form content, consider signing up for Office Hours with the Mass.gov Content team.

Overview tab

Title and Guide intro

The Title and Guide intro will be the first things your visitors see. In fact, they’ll often see them before they see your page, because these fields will appear in search engine results.

In the intro, offer a brief, high-level overview of what information can be found in the Guide. It’s important they be written clearly and in plain language. Try to write them using the words you think your audience would enter into a search engine to find them.

Header image

The Header image should be at least 1600 x 400 pixels. Like all Mass.gov images, it will adjust to the size of the user’s browser or screen.

You can adjust the focal point to make sure the right part of the image remains in view on small screens (e.g. mobile phones). Once you’ve added an image, use the little white crosshair in the Header image preview to pick the focus.

Picking the focus of the header image.
How the header image appears on the page.

Organization(s)

You’ll find the Organization(s) field at the bottom of the first tab in every Mass.gov content type, and in documents. This field tells Mass.gov’s search which pages belong to which organization. ‌ This field also powers the "Offered by" relationship indicator that displays at the top of all Mass.gov pages. "Offered by" displays on the top right if there is a "Part of" relationship indicator on the left in a desktop view, or on the top left if there is no "Part of" link. On a smaller screen, "Offered by" appears directly under "Part of" at the top of the page. ‌ Making sure your Organization field is filled out correctly will help users who land on your content find their way to your Organization Page.

Intended audience

Choose the audience this content is intended for. This information will help measure how well these audiences are being served and won't be displayed on the public-facing site. This is currently only for internal use. Choose from:

  • Not Set (default)

  • Personal

  • Professional (For their jobs)

  • Both equally

  • Unclear

Sections tab

Most of your information will be contained in sections. As a general rule, none of your Guide’s sections should be too detailed. Instead, summarize each topic and link users to more detailed How-to Pages or Information Details. We recommend that Guides include at least 3 sections, but not more than 8.

You can create a 1-column or 3-column section. You may only add Contact Information to 1-column sections.

In general, we recommend 1-column sections, as 3-column sections can be challenging to read. For mobile users, 3-column sections will be collapsed into 1-column sections.

Each time you create a section, its title will appear in your Guide’s table of contents:

This is a "sticky" table of contents, meaning it will remain on the top of the screen as a user scrolls down the page.

Time callout

Complete this if there is a consistent amount of time users should expect that task to take. Here’s what it will look like for users:

Stats and alerts

Stat

Use the stat field to highlight a takeaway statistic. Your section’s title and stat work together to make your guide scannable:

A stat is made up of the stat, the actual figure ("60 cents" in the above example), and the stat label, which briefly describes the stat or adds context ("Maximum liability...").

Alert

Alerts can help emphasize important deadlines and reminders:

Key actions

Use the Key actions to link users to more detailed pages, such as Information Details or How-To Pages. Using Key action links this way can help you limit how much content you need to include in each section, and reduce how much content users have to scroll through.

Pages you add as a key action will receive a relationship indicator. This acts as a "breadcrumb" for a user to find they're way back to the Guide after they've finished reading the information or completing the action on the subsequent page.

Example of a relationship indicator linking to Guide page.

Related tab

You can add up to 6 related Guides that will appear at the bottom of the page:

Was this article helpful?

Tell us what you think button