How to write for Mass.gov

Content authors should follow these core principles when writing pages for the new website.

Table of Contents

Introduction

People read web content differently than books or newspapers. Online readers scan pages quickly instead of reading each word. If they can’t easily find what they want, they’ll leave — usually within 10 seconds.

Because of this, it’s important to write in a way that is scannable and easy to read.

Tips for writing scannable content:

  • Use subheadings and bullets.
  • Limit yourself to 1 idea per paragraph.
  • Use short sentences and plain language. Mass.gov authors should aim for a Grade 6 reading level. Use the Hemingway App to see how your content reads.

Keep your readers in mind

Always start by thinking about what users need

  • Before writing anything, ask yourself some questions:
  • Who is going to read this?
  • What do they need to know?
  • How might they be feeling?
  • Help people find the information they need quickly and easily. Guide them through the process.

Do the hard work to make it simple

  • Use plain language and simple sentences.
  • Use clear, not technical, language.

Write for everyone

  • Respect the complexity and diversity of our users’ experiences.
  • Be willing to be surprised about who’s reading your content.

Build trust

  • Write like a person would speak.
  • Tell the truth.
  • Use positive language and concrete examples.

Start small and repeat

  • Make sure your content works for users. Don’t be afraid to scrap what’s there and start over.
  • Write a draft, test it out, gather feedback, and keep refining.

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 not here to explore, and they don’t want to read long pages of text. For this reason, every piece of published content on Mass.gov should be designed to meet a specific need.

If your content doesn’t help a user do something specific, it probably shouldn’t be on the website.

Give people what they want

Assumptions we make when designing a piece of content or service can often be wrong. To ensure we only put content on Mass.gov that is helpful to users, it’s critical to first define who that content is for and what that person is trying to do. We call this a “user need.” A user need may seem like a simple concept, but it can sometimes be difficult to put into practice.

Write content focused on user needs

Start by thinking about what your agency or organization does and the many people it serves.

  • As a… [who is the user?]
  • I need to… [what does the user want to do?]
  • So that… [why does the user want to do this?]

The user need should be written from the user’s perspective and in language that a user would understand.

Avoid using:

  • Understand
  • Know
  • Be aware of
  • Using (as in a tool or service)

You should only use “understand” or “be aware of” if the user needs to know it to fulfill a certain task, like comply with the law.

If a user doesn’t need a piece of information to take action, don’t include it. Complying with the law is still an action because it’s something users need to do to achieve something, like remain in business or avoid penalties.

Writing style tips for Mass.gov

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.

Use active voice — avoid passive voice

Be concise and direct when writing content for Mass.gov. Usually, the voice that best supports this style is the active voice.

What is the active voice?

The active voice focuses on who’s performing an action rather than the object that gets acted upon.

Why should you care?

Research shows that the active voice is easier to understand, and that it makes written content more engaging. This is important on Mass.gov, because users have a variety of levels of reading ability and online experience, and because the information is often complex.

Examples of active voice vs. passive voice

Example 1:

Passive voice: The request form must be submitted to the approving official.
Active voice: You must submit the request form to the approving official.

The active voice sentence focuses on the person who will submit the form. This person is entirely absent from the passive voice sentence! That feels impersonal — and can be confusing, too.

Example 2:

Passive voice: The case number should be saved in your records. It will be required for future inquiries.
Active voice: Save the case number in your records. You will need it for future inquiries.

Here, the passive voice is not only impersonal, it’s wordy. Longer instructions are harder to follow.

Use the passive voice only when it helps simplify a sentence. Never use the passive voice in a way that makes actions seem like they happen without anyone doing them.

Write in plain language — avoid slang and jargon

Government websites are for everyone. The content they contain should be as straightforward and clear as possible, which is why we use plain language.

What is plain language?

Picture your audience and write as if you were talking to them in person, with the authority of someone who can actively help them. This is plain language — the use of the simplest words to convey meaning.

Why should you care?

We use plain language to ease the burden on the reader and help them get straight to the information they need. Using complex words, government buzzwords, acronyms, and jargon confuses the reading experience and slows readers down from doing the thing they came to do. It can frustrate them or cause them to lose trust in Mass.gov.

Don’t use formal or long words when easy or short words will do.

  • Use “buy” instead of “purchase,” “use” instead of “utilize,” “help” instead of “assist,” “about” instead of “approximately,” and so on.

For a comprehensive explanation of plain language, review the Federal Plain Language Guidelines.

Use positive language rather than negative language

What is positive language?

Positive language focuses on what the reader can do rather than what they can’t.

Negative language: You cannot continue without signing in.
Positive language: Sign in to continue.

Address the user

Address the user as “you” wherever possible. Content on Mass.gov often makes a direct appeal to the public and businesses to take action. If you’re creating content that addresses many users — for example, a patient and their caregiver — address the primary user as “you” and refer to the other users by their roles or titles.

How to talk about the public

How you refer to the public is dependent on context. Feel free to choose from any of the words on this list:

  • People
  • Residents
  • The public
  • Folks
  • Constituents

We recommend against using the word “citizens” this way, 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.

Use contractions

In all of the communications we produce, we want to create a strong connection with our users. We want to give them the information they need in a straightforward way and show that we know what’s important to them. As a government organization, we need to sound somewhat official. But being official doesn’t need to be stuffy, archaic, or aloof.

Using contractions helps make written language sound more like spoken language. It also helps avoid perceptions of government as impersonal and detached.

To be continued...

These are just the basic principles we’re following as we write content for the new Mass.gov. We’re always working on improving and adding to them to create useful resources for you, our colleagues and content authors. Look for updates to this document. If you have questions about these principles, specific challenges you face writing content for your organization, or any of the other resources we’ve provided, please reach out.

Contact

Address

1 Ashburton Place
Boston, MA 02108

Feedback

Did you find what you were looking for on this webpage? * required
We use your feedback to help us improve this site but we are not able to respond directly. Please do not include personal or contact information. If you need a response, please locate the contact information elsewhere on this page or in the footer.
We use your feedback to help us improve this site but we are not able to respond directly. Please do not include personal or contact information. If you need a response, please locate the contact information elsewhere on this page or in the footer.

If you need to report child abuse, any other kind of abuse, or need urgent assistance, please click here.

Feedback