Style guide: How to write for Mass.gov
Use this guide for publishing content on Mass.gov, except when it is a law, regulation, or policy.
Writing for real people
Most people who visit Mass.gov want to do something specific – renew their driver’s license, apply for unemployment benefits, etc. They’re often not here to explore, and they don’t want to read long pages of text. For these reasons, every piece of published content on Mass.gov should be designed to meet a specific need.
Be direct – Write succinctly and to the point. Avoid the fluff.
Be clear – Don’t disappoint audiences with acronyms, internal language, or vagueness. Content should be simple and never vague.
Be confident – Confidence inspires audience action and comfort.
Be human – Write conversationally, as if you were interacting with the reader in person, 1-on-1. User personal pronouns – we, our, you, your – instead of formality.
We’ll explore all of these traits in more detail.
Consider your audience first
Before writing anything, ask yourself some questions:
Who’s going to read this?
What do they need to know?
How might they be feeling?
Your goal should be to help people find the information they need quickly and easily and guide them through the process.
Write content focused on user needs
Write content focused on audience wants Start by thinking about what your agency or organization does and the many types of people it serves:
As a… [who is the target audience?]
want to… [what does the audience want to do?]
So that I can… [why does the audience want to do this?]
Write from the audience's perspective using words they would understand. Avoid using terms, jargon, or processes they might be unfamiliar with.
Speak directly to the audience
Address the user as “you” wherever possible. This is known as second-person writing.
Likewise, when writing about your organization, use words like “us” and “we” and “our.”
Content on Mass.gov often makes a direct appeal to the public and businesses to take action. Addressing your audience conversationally helps users connect with the content and makes it easier to understand.
How to talk about the public
How you refer to the public is dependent on context. Choose from any of the words on this list: --
People
Residents
The public
Constituents
We avoid the word “citizens” as not everyone who uses Mass.gov is a citizen. Use “citizens” only when specifically writing about U.S. citizenship – for example, when describing who can vote in federal elections.
Make content easy to scan
People read web content differently than books or newspapers. They scan pages online instead of reading each word. Because Mass.gov visitors are heavily task-based, they want to find what they need quickly and easily.
Writing content that’s scannable is important. Scannable content means you:
Use subheadings (H2, H3, H4, etc.) and bulleted lists.
Limit yourself to 1 idea per paragraph.
Use short sentences and plain language.
These “chunks” of content become especially important on smaller screens, such as smartphones, where people leave pages even more quickly.
Abolish harmful or exclusionary language
There are many words used on the web that have started to be phased out due to their racist, gendered, or hurtful language or gendered meanings. We will follow suit, avoiding any hurtful terms.
Disabled, handicapped, impaired
Elderly, senior citizen
Gender and sexuality
Identity-based language
People-first language
Racist language
Other than referencing a proper noun, e.g. Executive Office of Elder Affairs or Disabled Persons Protection Commission, these types of phrases should be avoided.
You’ll find definition of these bullets deeper in the Editorial Style Guide. At its core, the content on Mass.gov should be welcoming to all and avoid excluding any constituents, residents, or visitors.
Mass.gov voice & tone
Millions of people visit Mass.gov every year. These visitors have widely varying experiences, perspectives, reading skills, and familiarity with the web.
Because of this, content on Mass.gov should always be respectful, friendly, and welcoming. When writing for Mass.gov, keep the following style tips in mind.
Mass.gov is:
Dignified but not boring. Write with authority and confidence, but don’t use artificial, overly formal language.
Helpful but not overbearing. Think of yourself as a customer service representative. Try to help people get stuff done.
Human but not casual. Be warm and personable, but don’t get silly. Mass.gov should be welcoming, but it’s still the voice of state government.
Write in plain language (grade 6)
Mass.gov authors should aim for a Grade 6 reading level. Using an app, such as the Hemingway Editor, can help you see how your content reads before publishing it. The best tip? Write as you would speak. Envision a constituent sitting on the other side of the table when you’re explaining something about how the state operates. This is plain language.
We use plain language to ease the burden on the reader and help them get straight to the information they need. Plain language also ensures accessibility, especially for people with lower reading levels or who speak English as a second language. Using complex words, government buzzwords, acronyms, and jargon confuses the reading experience and slows readers down from doing the thing they came to do.
Don’t use formal or long words when easy or short words will do. For example, use:
“buy” instead of “purchase”
“use” instead of “utilize”
“help” instead of “assist”
“about” instead of “approximately” etc.
For a comprehensive explanation of plain language, review the Federal Plain Language Guidelines.
Use contractions
As a government organization, we need to sound official. But this doesn’t mean being stuffy, archaic, or aloof. Contractions help make written language sound more like spoken language.
Use active voice
Be concise and direct when writing content for Mass.gov. Usually, the voice that best supports this style is the active voice, present tense – which focuses on who’s performing an action rather than the object that gets acted upon.
Active verbs – such as call, schedule, register, attend – don’t dwell in the past. Be active in your voice to inspire action from your audience.
Example of active vs. passive voice:
Passive voice (avoid): The request form must be submitted to the approving official.
Active voice (use): Submit the request form to the approving official.
Research shows that the active voice is easier to understand and that it makes written content more engaging.
Use passive voice only when it helps simplify a sentence.
Opt for positive language
Positive language focuses on what the reader can do rather than what they can’t. Positive language also reinforces actions from the user and takes less “cognitive load” to understand than negative.
Negative language (avoid): You cannot continue without signing in.
Positive language (use): Sign in to continue.
Editorial style guide & usage
To maintain consistency across the Mass.gov ecosystem, please follow these editorial style guide decisions in your content writing.
When possible, follow The Associated Press Stylebook (AP) guidelines and Merriam-Webster’s Collegiate Dictionary unless otherwise noted.
501(c)(3) – Never 501©3 or any other variations
& or and – Use & in page titles, page descriptions, and H1 and H2 headings. Use “and” everywhere else unless the ampersand or the word “and” is part of an official department or program name.
Abbreviations – In general, avoid alphabet soup. Do not use abbreviations or acronyms that the reader would not quickly recognize. An acronym is a word formed from the first letter or letters of a series of words.
Before a name: Abbreviate titles when used before a full name. Example: Mr., Mrs., Gov., Dr., Sen., etc.
After a name: Abbreviate junior and senior after an individual’s name. Abbreviate company, corporation, incorporated, and limited when used after names of corporate entities.
Acronyms – Spell out the name of the group or organization in the first reference (whether in a page title, header or text), followed by the acronym in parentheses. Use the acronym without periods in subsequent references.
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.
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)
Example: 1 Ashburton Place Suite 811 Boston, MA 02108
Bimonthly, biweekly – Means twice a month. To avoid reader confusion, write “meets twice a month” instead of using “bimonthly.” Biweekly means twice a week. To avoid reader confusion, write “meets twice a week” instead of using “biweekly.”
Bold and italics – Use bold only when emphasis is necessary, and even then, use sparingly. Never bold whole paragraphs, and avoid bolding entire sentences when possible. Never use bolded text to take the place of subheadings (H2, H3, etc.) Get more bold/italics tips from Siteimprove. See also: Punctuation > Quotation marks
Bulleted lists – Use bullets to break up text containing information that can be listed for easier scanning.
Use only to list three or more short items or for two lengthy items
Capitalize only the first word of each bullet item
Don’t use periods, unless a bulleted item contains more than 1 sentence
Whenever possible, use bulleted lists for 8-10 items or fewer. Break longer lists into multiple shorter lists or revise the copy to keep lists as short as possible
Keep your bulleted lists consistent. If some of the items in a list are sentences, make all of them sentences. If some items begin with verbs, begin all items with verbs. In short publications, such as brochures, try to structure all your lists the same way – either in sentences or not.
Buttons, calls-to-action – Use sentence case for button actions. Examples:
Complete your registration
Attend an event
Submit your application
Capitalization – Use AP style with the following exceptions and clarifications:
City, county – Capitalize only as part of a proper name. Example: New York City or San Diego County. Lowercase in other instances. Examples: the city of Richmond, the counties of Anderson.
Headers & subheads – See Headlines & subheadings
Names – Capitalize all words in an employee/volunteer/testimonial name. Example: John Smith, Jane Doe, etc.
Official departments and organizations – Capitalize all major words in the name of an official department or organization. Example: Department of Human Service
Titles (Roles) – Capitalize all words in an employee or board member’s title when preceding a proper name. Example: Vice President and CFO Jane Doe. Do not capitalize when they follow a name.
Choose, select – Use Choose or Select, which are ambiguous to devices, but not click, tap, or hit. See also: Select
COVID-19, pandemic language – Refers to the COVID-19 pandemic, specifically. Its name derives from “coronavirus,” which is a general term for a specific type of virus. For example, the winter flu is a strain of coronavirus; the COVID-19 virus is a coronavirus. Do not use ‘the’ in front of ‘coronavirus’ as coronavirus is many viruses.
It is important to keep consistency in mind during times of stress in order to maintain public trust and avoid panic. When choosing what words to use, we recommend agencies follow the lead of the Department of Public Health, the Governor’s office, and the Massachusetts Emergency Management Agency.
When writing about COVID-19 or other pandemics:
Outbreak - Sudden rise in cases of a disease in a specific place
Epidemic - Rapid spreading of disease in a certain population or region
Pandemic - Epidemic that has spread worldwide
Incubation - Period of time between infection and appearance of symptoms
Quarantine - Restriction of movement for healthy people who’ve been exposed to infection; separates sick people from healthy people
Social distancing - Maintaining distance and limiting contact in the outside world to limit the spread of disease (e.g. 6-foot guidance)
Hand-washing - Always a hyphen betwee words
Personal protective equipment on first reference, PPE on subsequent references
Define major organizations by name, then by acronym, e.g. Centers for Disease Control & Prevention (CDC) or World Health Organization (WHO)
Antiseptics kill germs on living things
Disinfectants kill germs on objects and surfaces
Dates – When a month is used with a specific date, abbreviate only Jan., Feb., Aug., Sept., Oct., Nov. and Dec. Spell out when using alone, or with a year alone. Do not use st, nd, rd, or th with dates. Use commas when giving the date, month, and year. Exampled:
Saturday, June 26
October 1984
Oct. 4, 2022
Disabled, handicapped, impaired – In general, do not describe an individual as disabled or handicapped unless it’s pertinent to the story. If a description must be used, try to be specific. Avoid descriptions that connote pity, such as “afflicted with” or “suffering from.” See more examples from the National Center on Disability and Journalism.
Blind - Describes a person with complete loss of sight. For others, use low vision.
Deaf - Describes a person with total hearing loss. For others, use partially deaf. Do not use mute, or deaf-mute. Never use deaf and dumb.
Mute - Describes a person who physically cannot speak.
Wheelchair-user - People who use wheelchairs for independent mobility. Do not use “confined” or “wheelchair-bound.” If a wheelchair is needed, say why.
Elderly, senior citizen – Use these words sparingly. As alternatives, use older adult(s), older person/people, but also specify if possible “people 65 and over.” Do not refer to a person as elderly or a senior citizen unless it is relevant to the story. It is appropriate in generic phrases that do not concern specific individuals, e.g. concern for the elderly. If the intent is to show that an individual’s cognition has deteriorated, cite a graphic example and give attribution. Use age when available and appropriate.
Fewer, less – In general, use fewer for individual items, and less for bulk or quantity.
Figuratively, literally – Figuratively means in an analogous sense, but not exact sense. Literally means an exact sense. Do not use it figuratively.
Gender and sexuality – Avoid using gendered terms unless it’s necessary. When possible, use gender-neutral terms for roles and jobs, such as “server” rather than “waiter/waitress” or “airline attendant” rather than “stewardess.” Use “they” as a singular pronoun rather than “guys” or “girls.” Other rules:
Don’t use same-sex marriage when referring to marriage. It’s just “marriage.”
Don’t use the words homosexual, lifestyle, or preference when referencing LGBTQ+ communities.
Words like lesbian, gay, trans, nonbinary, etc. can be used as modifiers, but never as nouns.
Use preferred pronouns or the person’s name, when not explicit. See “Pronouns” for information.
Headlines and subheadings – Headlines (H1s) should only exist to display the page topic or page title at the top of a page. Subheads (H2s, H3, H4, etc.) should be used hierarchically as needed.
Headlines and H1s should use sentence cases, without punctuation
Subheadings (H2s and below) should use sentence cases, without punctuation
Identity-based language – Identity-based language is a language that may be harmful or exclusionary by using euphemisms, slurs, or other oppressive words. When you’re unsure of the context of certain terms or language, do research to understand it further. Use the alternatives in parentheses.
Ladies and gentlemen (people, constituents, residents)
Policeman, congressman, statesman (Police officer, congressperson, etc.)
African-American (Black, always capital B) or use preference of subject
Walk-in (drop-in)
Lame (uncool, disappointing)
Handicapped (person with a disability)
“People of color” (BIPOC, or Black, Indigenous, and People of Color)
Transsexual (transgender people, trans, and gender non-conforming)
Transgendered (transgender)
Trigger warning (graphic content warning, upsetting content warning)
Links and link text – Links have 2 parts: The anchor text, or words to be clicked, and the URL, or web address that the words link to. Link using descriptive body text instead of pasting a URL directly in your copy. Don’t use “click here” for links.
Example: 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.
Good anchor text is an important part of accessibility and searchability. By linking to descriptive words rather than “click here,” you help people on assistive devices, like screenreaders, better know where the link is going. Descriptive link text also helps search engines, like Google, understand the relationship among content.
Linking to email addresses – Include “mailto:” in the hyperlink field before the email address when adding the link. Example: mailto:james@email.com.
Link to telephone numbers – Include “tel:” in the hyperlink field before the phone number, with no dashes. Example: tel: 5558881234
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.
Medical and mental conditions – Don’t refer to someone’s medical condition unless it’s pertinent to your story or content. Never assume a medical or mental condition. Never describe someone as “mentally ill.” If a medical condition is necessary, state it directly.
Avoid using phrases like lame, deaf (e.g. falling on deaf ears), blind (e.g. blind to truth), dumb even when not in reference to medical conditions.
Military rank – Capitalize before a name, and abbreviate. Use last name only on second reference and beyond.
Spell out and lowercase a title when it is substituted for a name: Gen. John Jones is the top U.S. commander in Afghanistan. The general endorsed the idea.
See AP Stylebook for abbreviations of ranks.
Months – Capitalize the names of months in all uses.
When a month is used with a specific date, abbreviate only Jan., Feb., Aug., Sept., Oct., Nov., and Dec.; Spell out March, April, May, June, and July.
Spell out when using alone, or with a year alone: January was a cold month or January 2016 was a cold month. But abbreviate when using with date: Jan. 2 was the coldest day of the month.
When a phrase lists only a month and a date, do not separate the date with a comma: His birthday is May 8.
In tabular material, use these three-letter forms without a period: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.
Numbers / Numerals – Use numerals for all numbers, unless they begin a sentence. Numerals are easier to scan for important information. Example: Our office includes 6 board members and 15 official volunteers.
Ages – When referring to ages of children or staff, use numeric and spell out “years old.” Example: Our first visitors to Santa at the Christmas Party were a 5-year-old girl and a 10-year-old boy.
Beginning of a sentence – If a sentence begins with a number, spell out the word. Example: Two hundred children attended the annual Christmas Party. Fifteen volunteers helped set up the event.
Dollars – Always lowercase. Use figures and the $ sign in all except casual references or amounts without a figure. Example: The book cost $4. Dad, please give me a dollar. For specified amounts, the word takes a singular verb: He said $500,000 is what they want.
Figures and words – Spell out first through ninth when indicating a sequence in time or location: first base, First Amendment, he was second in line. Use numbers for 10th (tenth) and above when needed.
Percentages – Use numerals for all numbers and the % sign instead of the word “percent” or “percentage.” Example: The department saw a 15% increase in revenue. However, when starting a sentence off with a percentage figure, spell out the number as follows: Twenty percent of recipients are new to the foster care system.
Telephone numbers – Use figures. Put parentheses around the area code. Use hyphens between number sets, unless otherwise preferred. Telephone numbers should be linked for click-to-call on mobile devices. If extensions are required, format it with abbreviation and numeral, for example: (800) 555-1234, ext. 2. 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
Temperature – With whole numbers, usually spell out degrees rather than using the degree symbol °. Do not use Fahrenheit or Celsius unless it is not clear which scale is being used. In cases when it is appropriate to use F or C, the form is 37°F. For temperatures exact to a tenth of a degree, use the form 98.6°F.
Times - Omit the :00 and use a.m. or p.m. (lowercase, with periods). If the range of hours are both a.m. or p.m., use them once. Use an en-dash without spaces on either side for time ranges. Example: 8–10 a.m. or 9 a.m.–2 p.m.
Years - 1970s or '70s. Use possessive only when referring to events in that time, e.g. 1970's. Spell out ‘seventies’ only when referring to someone's age. When a phrase refers to a month, day, and year, set off the year with commas: Feb. 14, 1987, was the target date.
Page titles – See Page Titles & Short Descriptions article
Pandemic – See COVID-19, pandemic language
Pronouns – Use the preferred pronoun of the person in the article. If you’re unsure of the preferred pronoun or identified gender, use they/them. Preferred pronouns may include:
He/him
She/her
They/them
Combination of the above
Punctuation
Bulleted lists – Don’t use periods, unless a bulleted item contains more than 1 sentence.
Colons – Use colons to offset a list. For example, I ordered three types of donuts: Vanilla, chocolate, and cherry.
Commas – Use the Oxford, or serial, comma. Add a comma after every item in a list, and before the last item. Example: I like the colors red, green, blue, and yellow.
Dashes and hyphens – Hyphens are used to join 2 or more words, as well as in phone numbers. Long dashes, known as em-dashes ( — ), signal a pause or 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.
Exclamation points – Use sparingly. If used to show excitement, use only one at a time.
File extensions – Use the letters capitalized without periods when referring to a file type. Example: PDF, JPEG, PNG. Use lower case in naming a file. Example: file.jpeg.
Parentheses – Use sparingly. Best used when referring to examples. Place a period outside a closing parenthesis if the material inside is not a complete sentence.
Periods – Periods go inside quotation marks, and at the end of sentences. They should not be used on bulleted lists unless bulleted list items are multiple sentences.
Quotation marks – Use quotation marks to refer to words and letters, titles of short works (like articles and poems), books, songs, movies, and direct quotations.
Semicolons – Don’t use semicolons. They don’t belong in plain language writing. Instead, break sentences into separate sentences.
Slashes – Avoid using the slash (/) symbol. Replace it with words or commas as appropriate.
Racist language – Abolish racist language. Many terms in technology have used black/white to describe bad/good practices. Use alternatives in parentheses:
Black hat / white hat (bad practice / good practice)
Blacklist / whitelist (bad list / good list)
Dark UX, dark patterns (bad UX patterns)
Grandfathered (legacy, longstanding) Master (main, primary)
White glove (premium service, top-notch service)
Religion, religious affiliations – Capitalize the names and related terms applied to members of orders. Example: He is a Catholic. He is a member of the Society of Jesus. See the AP Stylebook for all religions and affiliations and their appropriate usage.
Religious movements, such as the evangelical movement, should not be capitalized. Evangelicals, by and large, represent several broader denominations, particularly conservative Protestants.
Holidays and holy days should be capitalized. For example, Hanukkah, Easter, etc. See the AP Stylebook for specific holidays, their annual designation, and federal status.
Select, choose – Use ‘select’ or ‘choose’ to describe choosing an action, button, or link. Select is device-ambiguous and inclusive of all users across devices and assistive tools.
Short descriptions – See Page Titles & Short Descriptions article
That, which – That is the defining, or restrictive pronoun, which is the nondefining, nonrestrictive. Use a comma before “which.” Example: The lawnmower that is broken is in the garage. The lawnmower, which is broken, is in the garage.
They/them/their is acceptable in limited cases as a singular and/or gender-neutral pronoun when alternative wording is overly clumsy or awkward. Rewrite your sentences to avoid the problem, or, when all other options have been exhausted, use he or she (he or she is preferable to he/she, s/he, (s)he, and the like).
URLs, weblinks, and websites – Capitalize the names of websites and web publications. Don’t italicize. When quoting the organization link to their website. Example: For more information, visit the ACLU.
Do not capitalize the words “web” and “website” unless appearing as the first word of a sentence.
Always test the URL to make sure it works.
More info
If you have questions about anything not covered in this style guide, Mass.gov uses the following references:
Last updated