Welcome to Mass.gov. Here you'll learn the basics of the Content Management System (CMS), as well as how to create and save content.
Intro to Mass.gov & the CMS
Mass.gov was designed to be constituent-centered. People come to Mass.gov with a goal in mind, often to complete a task or to learn more information about something important to them. The easier we can make it for them to find and access this information, the better.
People aren't fluent in how the government works, and shouldn’t need to know which particular agency is responsible for the task or information they are looking for. They shouldn't (and don't) want to know what a dozen government acronyms mean in order to complete a step.
So when creating or editing a new page, we recommend asking yourself a series of questions:
Who is the audience for this page or group of pages?
How did the audience find this content?
Did they use a search engine?
Did they come from the Mass.gov home page?
Did they come directly?
What expectations did they have when seeking out this content, and what expectations have been established along their user journey here?
When you log in to the CMS, the author welcome screen will show several important pieces of information.
CMS welcome screen. Click to expand.
Latest Release Notes (Green box): The Mass Digital team updates Mass.gov every week with new code. This can contain bug fixes, changes to the author/editor user interface, and new tools and content types. This section will detail the most important aspects of the site’s most recent release.
Updates section (Yellow box): Provides summaries of and links to the most recent emails the Mass Digital team has sent to Mass.gov authors and editors, including site updates, tips or best practices, descriptions of new tools and features, alerts about bugs or other problems with the site, and updates about when a bug or error has been resolved.
Help and Support (Blue box): Quick links to resources you can use to find answers to your questions about the Mass.gov CMS, like the Knowledge Base, and to get in touch with the Mass Digital team through ServiceNow.
Content that needs attention (Red box): A table of links to content linked to your organization that gets high traffic but is scoring poorly according to the analytics the site automatically collects.
My recent content (Grey box): A list of the pages you have most recently worked on, in case you need to jump back into editing.
All Content & My Content tabs
When logged in to the CMS, you’ll probably spend most of your time in the “Content” tab. Here there are a few buttons of note
“All Content” tab will take you to a list of all of the content on the site. You can find specific pages or groups of pages by filtering or searching by organization, page type, authors, titles, scores, and more. This can be a good tool to use if you want to search all of the content on the site tagged to your organization, or if you want to see every page in a particular content type with high traffic or high scores.
Filtering content under "All Content" tab
The “My Content” tab has the same functionality of the “All Content” tab but filtered to just the content you have created, edited, or are watching.
When logged in to the CMS, on every page on Mass.gov you’ll see a button to “Watch” that page in the top right corner. Selecting this adds the page to your “My Content” tab (you will automatically watch any page you create or edit).
When watching a page, you will also get an email any time anyone edits that page detailing the changes that have been made. To remove a page from your “My Content” list and stop receiving emails about page updates, click “Unwatch.” Learn more about watching and unwatching content.
How to watch content.
How to unwatch content.
Adding content & documents
Next to the “Content” header you’ll see buttons called “Add content” and “Add a document.” Use these to create, respectively, new HTML pages and to add files, such as Word documents and PDFs, to the site. Learn more about HTML vs. documents.
"Add content" button in the header menu.
When you select the “Add content” button, you’ll be taken to a page that lists all of the content types (aka, page templates) on Mass.gov and gives a short description of them, with a link to find more information about that content type in our Knowledge Base. Once you select the content type you would like to start making, you’ll be taken to a Create page.
The Create page will display dozens of fields over several different tabs that make up the separate elements of your new page. Fields that are required for publishing are marked with a red asterisk. Watch video on how to add content.
"Add document" button in the header menu.
Adding a document works the same way as adding new content types–there are multiple fields over two tabs to add identifying information for your document. Required fields are marked with a red asterisk. Learn more about how documents work.
Common content types
Learn more about typical content types you'll likely use as a new author.
Organization pages, or “org pages” present an overview of a directorate or agency, showing their key services and functions. They point to Topic pages that help describe the organization and its operations, with a goal of helping to illustrate the structure of the state government and guide users toward their area of interest. Org pages can also offer pages containing documents (such as budgets and policies), events and news related to the organization, and contact information.
Topic pages collect services and other Topic pages about or adjacent to a broad, central theme, and give users an opportunity to find a variety of transactions and information we have on the site around that topic, regardless of whatever organization offers them.
The goal of these pages is usually to eventually get someone to a Service or other page where they can do or learn something. Only Mass Digital can create Topic pages and fill in certain fields, so if you’d like a new one, or see changes on an existing page that you can't make, just file a ServiceNow ticket and we’ll get in touch with you.
Service pages are the backbone of our site structure. They’re what the average user is most often going to be looking for when they come to Mass.gov, and what the rest of the site architecture is built off of.
Generally, Service pages detail a transaction or a collection of transactions that a user can complete on Mass.gov pages or on some other website, and informational or instructional pages that support those transactions. They contain child pages that broadly fit into one of two categories: transaction-based and informational.
Transaction-based pages typically live under the “What would you like to do” section of the Service page
Informational pages live under the “What do you need to know” section, though Service pages can also be configured using custom link groups in which the author defines the heading for each collection of links.
Service pages also have three spots for featured links, and most child page types can fit into this section. The best place to link to other Service pages within a Service page is in the “Related services” section.
Service pages must be linked up to Organization pages so that users know who is offering that service and can get in touch with them if needed. Ideally, Service pages should also be linked up to Topic pages, where users can find other related services and information.
How-to pages are transaction-based pages that offer the user an opportunity to quickly complete a one- or two-step transaction, either on Mass.gov or offsite. They feature a section we call “Quick Actions” that gives users a quick link to whatever the main transaction of the page is–download a form, log in to an offsite app, discover eligibility, etc., at the top of the page.
If your how-to page doesn’t have a transaction, it might be better suited as an Information Detail page. Our best practice for How-to pages is to include contact information, so that users know who to reach out to with questions.
Guides are for transactions that contain multiple steps or require a lot of information to complete or a collection of smaller transactions that don’t necessarily merit their own How-to pages. They have a clickable navigation menu, so users can easily jump to a specific section if they’re only looking for certain information.
If your Guide does not have any transactions within it, it might be better suited as an Information Detail page. Ideally, guides use key action links, statistics, and time callouts within sections to get users the information they need quickly.
Information Details pages (or Info Details) are designed to convey large amounts of information, broken up into sections. They have a clickable navigation menu, so users can easily jump to a specific section if they’re only looking for certain information. If your Information Details page is just a list of documents or links to other pages, it might be better suited as a Curated List. If your page is getting very long, it might be better suited broken up into a Binder.
Curated Lists are collections of related documents, contacts, forms, regulations, Mass.gov links, or offsite links, that a user would want to have all in one place, so they can access them at or around the same time. Curated lists can be automated so that any page or document with a specific label is automatically added to the list, or manual, which are manually maintained by authors. There is a special type of curated lists just for contact information that authors can use to create an organization directory.
Binders are a long-form collection of content that is meant to be read together sequentially, like a report or a book, broken up into sections. They have a clickable table of contents and links that will take you to the next and previous sections.
There are more page types than these, but at its most basic level, our core content is structured from Organization pages to Service pages, and from Service pages to what we call "Service Children" pages, which include Binders, Curated Lists, Guides, How-tos, Info Details, Regulations, and Service Details.
Ideally, users will begin on a page that is broad in nature and then filter down to more and more specific pages as they continue their journey on the site.
The general hierarchy for the core of Mass.gov pages.
How people navigate Mass.gov
People might skip the Org page step if they choose one of the top-level Topic pages on the home page, listed in the menu under “Living,” “Working,” etc. But generally, this is the ideal path web visitors should take – starting at broad or general pages, and moving down the funnel to more and more specific or focused pages.
However, thanks to search engines, link-sharing, newsletters, etc., people might enter the site at any point in our hierarchy. If we’ve done our jobs right, the user journey will still continue down in the same way. For example:
If someone Google searches for a specific action, they might end up on a Service page, but should be able to easily find the How-to page or Guide where they can complete a transaction.
Or, maybe they find an Information Details page where they can learn more about the service.
At any page they land, it should be easy for someone to move up the funnel to a Topic or Org page to find broader information, if needed.
That's why it's vital that everything is connected and linked appropriately and efficiently. The autofill feature helps prevent links on Mass.gov from breaking, ensuring content remains accessible.
How to help people navigate
First, while there are a few exceptions, every page created should be linked up to a page in the level above it, especially at the lowest level. So, every How-to page, Information Details page, Curated List, etc. should be connected to a service. When a child page isn’t linked up to a Service, we call that an orphan page.
Orphan pages can be very difficult for users to find unless they know exactly what to search. Additionally, if someone finds themselves on an orphan page and it isn’t quite what they were looking for, it could be unclear where to logically go next to find what they need.
It creates a relationship indicator link in the top right corner of each page, which provides both context for the information on the page, and creates an easy link to the level above in case the user is lost or the page doesn’t have the information they are looking for
It tracks certain analytics to determine the success rate of each specific page, the service it is connected to, and the site as a whole. You can see some of these analytics on a page-by-page level in the analytic dashboards.
Drafting & publishing content
Publishing options in the CMS.
When it is time to save the page you have been working on, you’ll have a few options. If you scroll down to the bottom of the edit window, you’ll see a dropdown selection field with 5 options followed by 2 buttons: “Save” and “Preview.” Here are terms and statuses for pages you'll see:
Selecting this option and clicking the “Save” button will turn the draft of the page you are currently working on live, making it viewable and findable to the general public. Do not select “Published” until the page is ready for public access.
Only users with “Editor” capabilities can publish content in the CMS. “Authors” may edit and save drafts, but will need an Editor to publish their pages.
This option is most useful for Authors who do not have Publishing privileges. It's helpful whe content needs to be reviewed internally.
This option will save the page you’re working on without making it live on the web, so you can come back to it later and make further changes or publish it when you are ready.
You can save an unpublished draft of a published page, so the live version of the published page will still be available to the public. Only one draft of a published page may be saved at a time, so if you need to make a draft different from one that is already saved on a published page you will need to delete or undo your first draft.
Unpublishing a page removes it from the live web but keeps the page in the CMS. This is a good option to remove a page from public consumption but keep it in case it will need to be published live again at a later date. Unpublished pages will still appear in the “All Content” tab and the “My Content” tab.
This option will unpublish a page and remove it from the CMS. Trashing a page is a good option for a page that has reached the end of its usefulness and will not be published again. Trashed pages will not appear in the “All Content” and “My Content” tabs. If you want to redirect a page’s URL to a different page, the page will need to be Trashed.
The CMS allows us to schedule a specific date and time when an unpublished page will become a published page, and vice-versa. We don’t have the functionality to schedule when a draft on top of a published page will go live–these have to be published manually.
In addition to the publishing options above, you can also choose to create a temporary access link to a draft or unpublished page. These links are best used to share a page that is not yet public-facing with someone who does not have a CMS account, for review or approval.
Note that a page will need to be saved in some form first before the option to create a temporary access link will appear.
The longest-lasting temporary access link available will stop working after two weeks, but we recommend using one of the shorter options if possible.
We recommend having contact information on every page where it is possible, as this is brought up more often than anything else in user feedback
Linking using the autofill is always preferable to hard linking. Using autofill helps us measure page analytics for scores, creates relationship indicators, and ensures that you won’t have to go back and manually change links if a link is updated.
If you’re logged in to the CMS, you can jump directly to the “Edit” mode from any Mass.gov page by selecting the URL and changing “www” to “edit”. That way, you don’t have to go searching in the All Content or My Content tab to update a page.
Low scores (red and yellow numbers) in the “Page Health” tab in the Web Analytics dashboard might be a sign that we’re using the wrong page type for that content
Any page on Mass.gov might be someone's first entry point, so use titles and short descriptions that are as descriptive and specific as possible, since someone might not have seen the org or Service page first and would therefore lack that context
Service pages can be linked from more than one Topic or Org page, and service children can be linked from more than one Service page
The Hemingway app is a useful tool to help find an accessible reading level:
The user feedback tool is your friend. Monitoring that tab on high-traffic pages is a great way to see if the page is unclear or missing something.
Public & visitor feedback
One of the most helpful tools that Mass.gov authors and editors have when it comes to improving their content is user feedback.
At the bottom of nearly every page on Mass.gov users have the option to fill out a survey to indicate that they did or did not find what they were looking for on that page, and leave a comment if they choose. These responses are collected in 2 places for authors and editors to review.
First, when logged in to the CMS you can see the feedback left on a specific page by accessing the “Feedback” tab in the edit menu, right next to the button for the “Edit” tab you use to edit your content. Sitewide feedback is also collected in the main “Feedback” tab next to the “All Content” and “All Documents” tabs. Like those pages, the main “Feedback” tab displays all feedback left across the site, and can be filtered by organization, content type, and more.
Finding the sitewide Feedback tab.
Finding the Feedback tab in the edit menu.
It's important to monitor your pages' feedback to see if there are any improvements you can make to it. If the same question or issue is repeated on a specific page, there might be a false expectation set up somewhere on the typical user journey to that page. You can think about editing the page itself, or one of the pages that most often link to it.
Web Analytics Dashboards
The Web Analytics Dashboards help you assess and monitor how content is performing. The data is pulled using a variety of different tools: Google Analytics, Siteimprove, and other sources. The Web Analytics Dashboards collect and evaluate data specific to each content type, and separates it into 3 tabs:
This tab is designed to give you a high-level overview of how your page is generally performing. In each of the boxes, if the number is green the page is probably doing A-OK, if the number is yellow there might be ways that we can improve it, and if the number is red there might be cause for concern.
Finding audience analytics.
The Audience tab is where you will find information about the amount and types of traffic that the page is receiving during a specific period of time. It can give you a good idea of how many people are using your page and how they are finding it.
Finding visitor interactions analytics.
The data in the Visitor Interactions tab is all about what users do once they get to your page–what links they click on, where they go next, and whether they used our feedback form to indicate that they did or did not find what they were initially looking for.
We’re always looking to improve these dashboards, so if there is a way we can make them better–add information that would be helpful that isn’t currently there, tweak the language for a section that isn’t clear, etc.–please let us know.
Mass.gov authors and editors have access to a variety of third-party applications to help create, monitor, and improve digital content. Here’s a brief summary of what you have access to as part of your Mass.gov subscription:
Siteimprove: This is a helpful tool for tracking and improving things like broken links, reading level, page accessibility, search engine optimization, and more. Siteimprove powers many of the items tracked within our Web Analytics Dashboards, and you can use their site to access more features. Learn more about Siteimprove.
Google Analytics: Google Analytics, or GA, is our main analytics tracking tool for measuring things like page traffic, page events, and user journeys. Like Siteimprove, we use GA to measure a lot of the metrics in the Web Analytics Dashboards. You can create a Google account with your Mass.gov email address to access and use the full Google Analytics suite of tools. Learn more about GA.
Formstack: This is Mass.gov's preferred tool for creating and managing forms. You can create forms to be embedded on Mass.gov, or to use offsite in things like email and social media. Learn more about Formstack.
Hootsuite: Mass.gov has an enterprise Hootsuite account to help organizations draft, schedule, and track social media messaging. Learn more about Hootsuite.