Style guide

This style guide should be used by anyone writing content that will end up posted on Mass.gov, except when that content is a law, regulation, or policy.

General rules

To make your writing as accessible and web-friendly as possible:

Example:

“Renew your driver’s license…” instead of “Renewing a driver’s license”

  • Structure your content to make it scannable. Put the most important information first and use headers, bulleted lists, and short paragraphs to break up your text.

  • Be concise. Use short sentences and contractions where it’s natural to do so.

  • Don't use all caps in the middle of sentences

Example:

To complete your application, you must complete forms x, y, AND z.

Acronyms and state organization references

Acronyms often confuse readers. Avoid them where possible.

If you're going to use an acronym a lot, spell out the full name or phrase the first time and out the acronym in parentheses on the first reference.

Example:

The Department of Transitional Assistance (DTA) assists and empowers low-income individuals and families to meet their basic needs, improve their quality of life, and achieve long term economic self-sufficiency. DTA serves one in eight residents of the Commonwealth with direct economic assistance (cash benefits) and food assistance (SNAP benefits), as well as workforce training opportunities.

Use "our" to refer to your organization.

Example:

Welcome to the Office of the Comptroller of the Commonwealth. Our mission is to promote accountability, integrity, and clarity in Commonwealth business, fiscal, and administrative enterprises.

Formatting

Never use underlines. On the web, underlines are only used for links.

Links have 2 parts:

  1. The anchor text, or words that can be clicked

  2. The URL, or web address, that those words link to

Don't add URLs directly into your content without anchor text.

Good anchor text is an important part of accessibility and searchability. Don’t use “click here” or other non-specific language. Instead, try to explain where you’ll go if you click the link, matching the title of the destination page if possible.

Examples:

SNAP benefits, formerly the food stamps program, are part of a federal program to help people with limited means pay for food. You can find out if you are eligible for SNAP benefits online or by calling the Department of Transitional Assistance’s (DTA) helpline at (877) 382–2363.

Sometimes it isn’t possible to be crystal clear. Use common sense, trying to strike a balance between the clarity of your writing, matching the page titles, and telling the reader exactly where the link leads:

There are several ways to apply for MassHealth. You can apply as an individual or family (including those with disabilities), as a senior or for long-term care, or as someone seeking help with Medicare Part B premiums.

Linking to email addresses or telephone numbers

To link to an email address: mailto:james@email.com

Email James at james@email.com

To link to a phone number: tel:1234567890

Call James at (123)-456-7890

Linking to non-government websites

Only link to non-government websites that provide government information or services that can't be made available on Mass.gov. Please refer to the Mass.gov linking policy before linking to non-government websites.

Punctuation and capitalization

Commas: Use the “Oxford” (or serial) comma. Add a comma after every item in a list, including the second-to-last one.

Example:

I like the colors red, green, blue, and yellow.

Semicolons: Don’t use semicolons. They don’t belong in plain language writing.

Bulleted lists: Capitalize the first word of each item. Don’t use periods, unless bulleted item contains more than 1 sentence.

Don't repeat introductory sentence material within bullets

Dashes: Hyphens are used to join 2 or more words, as well as in phone numbers.

Long dashes, or en-dashes ( — ), signal a pause or an independent statement. Add a space on either side and don’t capitalize the first word after the en-dash.

Example:

Both are highly treatable if caught early — women who received a diagnosis early had a survival rate of 98.5 percent — which is why regular screenings are so important.

Slashes: Avoid using the slash (/) symbol. Replace it with words or commas as appropriate.

Headings: Use sentence case  — it’s easier to scan and read lowercase words. That means capitalize the first word, but leave the rest of the title lowercase (except for words that would normally be capitalized, like proper nouns).

Personal titles: Don’t capitalize personal titles unless they precede a name. For example, the director got approval or Director Lopez got approval.

Numbers

Don’t spell out numbers, unless they begin a sentence. Numerals make it easier for readers to scan for important information.

Example:

There are 2 ways of filing for unemployment or there are 6 steps required to complete a particular form.

Addresses

Format street addresses as follows:

  • Line 1: Street address (Use numbers and only abbreviate St., Blvd., and Ave.)

  • Line 2: Use for floors, suites (Spell out and use capping for floors and suites)

  • Line 3: City, State ZIP (2-letter state abbreviation with no punctuation, 5-digit ZIP code)

Examples:

1 Ashburton Place Suite 811 Boston, MA 02108

1 Ashburton Place 8th Floor Boston, MA 02108

Phone numbers, dates, and times

Phone numbers

  • Use parentheses around the area code. Don't add "1."

Example:

(800) 111-2345

  • Don't use letters for phone numbers. Phone numbers with letters prevent people from using “click-and-call” on their mobile devices, and they are not accessible.

Example:

Instead of (800) STEEMER, use (800) 783-3637

Dates

  • Spell out the month unless it's used with a date

  • Don't use st, nd, rd, or th with dates

  • Use commas when giving the date, month, and year

Examples:

January 2019

Jan. 3

Jan. 3, 2019

Times

  • Omit “:00”

  • Use “a.m.” or “p.m.” (lowercase, with periods)

  • If both hours are "a.m. or "p.m.," only use them once.

  • Use an en-dash without spaces on either side for time ranges. An en-dash (–) is slightly wider than a hyphen (-) but narrower than an em-dash ( — )

Examples:

8–10 a.m.

9 a.m.–5:30 p.m.

More info

If you have questions about anything not covered in this style guide, Mass.gov uses the following style guides:

Was this article helpful?

Tell us what you think button