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.
To make your writing as accessible and web-friendly as possible:
Avoid jargon. Use simple words most readers are familiar with.
Address the reader reading the page when possible. Use “you” instead of “my.”
“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
To complete your application, you must complete forms x, y, AND z.
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.
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.
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.
Never use underlines. On the web, underlines are only used for links.
Links have 2 parts:
The anchor text, or words that can be clicked
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.
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 link to an email address: mailto:firstname.lastname@example.org
Email James at email@example.com
To link to a phone number: tel:1234567890
Call James at (123)-456-7890
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.
Commas: Use the “Oxford” (or serial) comma. Add a comma after every item in a list, including the second-to-last one.
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.
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.
Don’t spell out numbers, unless they begin a sentence. Numerals make it easier for readers to scan for important information.
There are 2 ways of filing for unemployment or there are 6 steps required to complete a particular form.
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)
1 Ashburton Place Suite 811 Boston, MA 02108
1 Ashburton Place 8th Floor Boston, MA 02108
Use parentheses around the area code. Don't add "1."
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.
Instead of (800) STEEMER, use (800) 783-3637
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
Jan. 3, 2019
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 ( — )
9 a.m.–5:30 p.m.
If you have questions about anything not covered in this style guide, Mass.gov uses the following style guides: