Mass.gov 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:

• Use plain language written at a 6th grade reading level. Use the Hemingway App to test your draft.
• Address the person reading the page when possible. Use “you” instead of “my.” Example: “Renew your driver’s licence…” 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 contractions where it’s natural to do so.

Acronyms and state organization references

Acronyms often confuse readers. Avoid them whenever possible.

If an acronym is necessary for future reference, spell the full name or phrase and follow with the acronym in parentheses on the first reference. For example, “Department of Public Health (DPH)” on its first mention on a page, then DPH for any subsequent mention. Make the spelled out version of the name into a link to the organization’s home page.

Formatting

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

Links

Links have two parts: the anchor text, or words that can be clicked; and the URL, or web address, that those words link to. You should not add URLs directly into your content without anchor text.

Good anchor text is important. 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.

To add a link (this works in Word, Google docs, and many other places)

1. Go to the page you want to link to and copy the URL (web address).
2. Go to your document. Select your anchor text (the words that will be clickable).
3. Press control (Windows) or command (Mac) + K to open the link pop-up.
4. Paste the link you copied in step 1.

Punctuation and capitalization

Commas: For clarity, use the “Oxford” (or serial) comma — that is, 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.

Lists: Capitalize the first word of each item. Add a period to the end of a list item only if it’s a full sentence. Example:

• Item 1
• Item 2

vs.

• This is the first item.
• This is the second item.

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

Long dashes, or em-dashes ( — ), delineate a pause or insert an independent statement. Add a space on either side and don’t capitalize the first word after the em-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.

Titles and headings: Use sentence case whenever possible, including for titles and headings — 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).

Numbers: Don’t spell out numbers (unless they begin a sentence). Numerals make it easier for readers to scan important information (like the 2 ways of filing for unemployment or the 6 steps required to complete a particular form).

Addresses

Format street addresses as follows:

• Line 1: Street address (Use all arabic numerals. Only abbreviate St., Blvd., and Ave. Spell out Road, Place, etc.)
• Line 2: Secondary street address for floors, suites (Spell out and use sentence case capping for 8th Floor, Suite 811, etc.)
• Line 3: City, State ZIP (2 letter postal code abbreviation with no punctuation, 5-digit ZIP code)

Example:

1 Ashburton Place
Suite 811
Boston, MA 02108

1 Ashburton Place
8th Floor
Boston, MA 02108

Phone numbers and times

Phone numbers

• Use parentheses around the area code. Example: (800) 111–2345
• Do not use letters for phone numbers. Example: Instead of (800) STEEMER, use (800) 783–3637. Phone numbers with letters prevent people from using “click-and-call” on their mobile devices, and they are not accessible.

Times

• Omit “:00”
• Use “a.m.” or “p.m.” (lowercase, with periods)
• 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 ( — )
• Example: “9 a.m.–5:30 p.m.”