Creating accessible content
Mass.gov was designed with accessibility at the top of mind. Learn how authors and editors can create accessible content for everyone.
Mass.gov was designed with accessibility at the top of mind. Our colors, fonts, and designs were chosen specifically with accessible use in mind, to ensure that all audiences would be able to use the content on the site.
There are factors that will make your content more easily accessible, giving your audience the best experience possible.
At a high level, here’s how to make content more accessible:
Break content into chunks that can be quickly scanned and digested
Write in plain language and avoid jargon
Use descriptive links rather than “click here”
Add alt text to images, captions to videos, and transcripts to audio or video files
Use appropriate color contrast for text
Avoid PDFs, when possible, and move content to a webpage (HTML)
Our goal should always be to make the Mass.gov website experience as accessible and inclusive to all readers as possible. According to the W3C Web Accessibility Initiative, web accessibility is the websites, tools, and technologies designed and developed so that people with disabilities can use them. Specifically, so people can:
Perceive, understand, navigate, and interact with the web
Contribute to the web
Break content into digestible chunks
Writing for accessibility is more than writing with correct spelling and grammar. It also means organizing content in a way that's scannable and readable. It means your content is understandable for everyone.
It also uses metadata to help users understand the content, no matter how they choose to browse it.
As you write, ask yourself these questions:
Would someone be able to easily translate it to their preferred language?
If someone was using a screen reader to narrate what’s on the screen, would the order and cadence make sense?
Can someone on a small device, such as a smartphone, quickly and easily scan the page to understand it at a high level?
Create a structural & visual hierarchy
Pages should only focus on a single topic. When creating a page of content, use the inverted pyramid to structure the page. This style of writing helps you focus on the most important information first, while also creating meaningful subheads to introduce new information and help users scan the page.
When using subheadings, be sure to nest appropriately:
There should only be one H1 per page, and that’s the page title
Use H2s to introduce new topics
Use H3s to create subheads under H2 sections
Use H4s under H3s, and so on
Write in plain language
Plain language is preferred by all people online, regardless of education. In fact, Nielsen Norman Group has found that even experts and doctorate graduates prefer plain language over jargon.
Plain language is reader-focused, using an active voice and everyday language. It uses only as many words as necessary. It’s especially helpful to people who translate content into other languages.
Avoid using overly technical jargon, especially acronyms, as often as you can. Some screen readers interpret acronyms by reading every letter individually, which can become tiresome if one is repeated often on a page. If you have to use an acronym, always define it on the first reference to give your audience context.
Reading level: Grade 6
Aim for a reading level of grade 6, and use tools like HemingwayApp to help write clearly. A grade 6 reading level is important because it:
Helps provide more accurate non-English translations
Makes content accessible to people with lower reading levels
Makes content easier to scan and digest quickly
Avoid directional language
Because websites are responsive, content changes based on the size of the screen used. Avoid using directional language such as above, below, left, or right.
Good: Select from these options.
Bad: Selection from the options below.
Use descriptive links
To help people who use screen readers understand the context of each link, be sure that the text you use for hyperlinks describes both the link’s destination and purpose. This will give constituents using screen readers the info.
Never use the words “click here” or “learn more.”
Instead, use descriptive links. These help people understand the context of the link before they click or select. Describe links that highlight the subject, not the action.
Good: Contact us for more information about our services.
Bad: Click here to contact us for more information.
Add alt text to images
Alternative text, or alt text, is an image description. It should be included on all images, graphs, and charts to tell people what an image is.
Alt text also helps search engines index the images.
When creating a page of content, make sure every image has alt text. See examples of good alt text.
Most important
Be brief—less than 250 characters (100-125 is ideal).
Don’t just describe the image but explain its purpose.
Include key words people might use when searching on the page.
Don’t use all caps or include “picture of” or “photo of” (unless the medium matters).
Don’t put text in images, as these can’t be read by assistive devices, such as screen readers.
Tips
If you’re using the Mass.gov image library, check there to see if there is already alt text for the image.
If you’re seeking examples of alt text on a webpage or just want a quick way to see alt text:
Right click on an image and select "Inspect."
This will open the developer tool panel on the right side of the screen.
The image's details will be highlighted in the panel on the right.
Types of images and their alt text
Informative images
Images that graphically represent concepts and information, typically pictures, photos, and illustrations. The text alternative should describe the essential information presented by the image.
If the image is a graph or chart, do your best to describe what the data shows, including important information such as highest or lowest categories or significant trends.
If the image is a portrait or profile, include the name of the person.
Decorative images
If the image is not essential to the content, there's no need to describe it but do include "null" in the alt text
Images of text
Readable text is sometimes presented within an image. If the image is not a logo, avoid text in images. However, if images of text are used, the text alternative should contain the same words as in the image.
For embedded videos, include closed captions and a link to a transcript that describes both the written or spoken text in the video and the visual elements shown on screen. If you’re creating a video with the Mass Digital team, we’ll provide this transcript for you.
Use closed captioning and transcripts
If the page you’re creating features audio or video files, make sure closed captioning and/or a transcript are available.
While YouTube and other video providers do auto-captioning, they’re often not correct. When possible, provide your own accurate captioning for accessibility.
Use HTML when possible
The Mass Digital team strives to make state services and information easy for constituents to find and use on Mass.gov. One way to make content user-friendly for the most people is to make HTML pages on Mass.gov rather than to upload documents (PDFs, spreadsheets, etc.).
There are several reasons why HTML should be your default:
HTML is more accessible for all audiences. Mass.gov is built to be accessible and continually adds enhancements to be more accessible (as you can see in our weekly Release notes). PDFs., PowerPoint presentations, spreadsheets and docs are not automatically accessible, so you need to use accessibility checkers to ensure compliance with WCAG standards and make the necessary changes manually if they do not comply. (For these reasons, HTML pages are also easier to maintain and keep up to date than documents and PDFs.)
HTML is responsive so that content adapts to different device type screens for easy viewing. PDFs and other downloads are not responsive, and users on cell phones and tablets end up having to zoom in and out or scroll vertically or horizontally to read pages, view images, or make sense of graphics.
Findability is easier on HTML whereas users may struggle to find content they download, especially on phones or tablets. A PDF might be hard to find if it opens in an app or a new tab or window, and we cannot assume all devices have PDF viewers built-in. Also, tracking down the document may take the person away from the original website where they might need the larger context for the download. If search results take the user straight to a PDF, they miss any context they might need on the site it came from. (For users accessing Mass.gov content on mobile, the storage space taken up by downloads is an additional burden.)
HTML is easier for search engines to crawl. Google, Bing, etc. crawl your HTML pages and return relevant results based on what they find in the content. They do not crawl downloads.
You can track analytics showing how users are interacting with your HTML content, but aside from tracking clicks on downloads that happen on our site, you cannot see how visitors are interacting with them. Any clicks to downloads from public search engines or external sites are not tracked, so we don’t have reliable data on how often documents are used.
PDFs, docs, etc. are more work to maintain and update and cannot be scanned for broken links.
There are a few use cases for downloadable content on Mass.gov pages:
If your whole purpose is to provide your audience with downloadable content to be available offline, such as:
A translated document
A data file
An interactive spreadsheet
A form that people need to print and sign (and creating a Form page is not an option)
A form or document that needs to maintain its precise format
If the content contains math symbols or characters not easily rendered in HTML
If there are visual elements interspersed with text
If it’s timely and you must get the information up immediately, you can upload the content as a document temporarily while you build the HTML version.
Make documents accessible
Any documents (PDFs, Word docs, PowerPoints, Excel spreadsheets, RTFs, etc.) that appear on Mass.gov must meet accessibility guidelines.
There are many tools for checking the accessibility of various kinds of documents.
*Note: If you are an author who publishes documents created by others (such as a subject matter expert), we encourage you to share these resources with them and/or collaborate with them to make the documents accessible. Otherwise, you might find yourself repeating the steps to make the content accessible the next time it is updated or reproduced.
If you will be including documents on your pages and if creating them in HTML is not an option (see above), use the resources below to check their accessibility, and then make any necessary changes to ensure compliance.
Check the accessibility of Word, PowerPoint, and other Microsoft Office documents:
Word, PowerPoint, and other Microsoft Office products, have a built-in, easy-to-use Accessibility Checker that can highlight problem areas in your document. Even if you plan to turn your file into a PDF, run the Accessibility Checker before doing so.
Once you've done an Accessibility Check, you can convert it to an accessible PDF.
Check the accessibility of PDFs:
Adobe Standard and Pro have built-in tools for checking and fixing accessibility as well. In the left-hand menu, select "Prepare for accessibility" (you may need to click "View More" to see it), and then "Check for accessibility." Select "Start Checking" on the window that pops up. A list of issues that have been checked will appear on the right-hand side, showing which items passed, failed, or require a manual check.
You can right-click any item in the list to learn more, run a new check on that item, manually mark it as pass/fail, or access tools to address the issues.
You can also view a recording of our Accessible PDFs Workshop to see the Adobe acessibility checker in action.
Check out these guidelines from the Data Office about creating accessible spreadsheets.
Make forms accessible
To comply with WCAG accessibility standards and offer Mass.gov users a better digital experience, you should not create forms that ask people to enter the same information twice in the same session. ("Same session" is defined as a sequential interaction with a form before a user hits the submit button.) This standard is intended to support
people with cognitive issues who have difficulty remembering what they entered before
people who have difficulties typing or entering information even with their assistive devices
Authors should design forms that prevent users from having to re-enter information they’ve already entered before to reduce cognitive load, unless:
re-entering the information is essential
the information is required to ensure the security of the content, or previously entered information is no longer valid
This screenshot illustrates an exception to the standard: an account signup form asks for the password twice for security.
How to meet this standard
If the exceptions do not apply, authors should check existing forms for multiple same information entries and revise them. They should also ensure that all newly created forms are in compliance.
If the exceptions do apply, authors should still consider alternative ways to confirm information already entered. For example, you can use a checkbox to copy previously entered information to a form where duplicate information is necessary. In the below sample, the checkbox avoids having users enter the address again if their billing address is the same as the shipping address.
Check Formstack for features to enable copying/filling previously entered information by users.
Abolish harmful or exclusionary language
There are many words used on the web that, at one time the standard, have started to be phased out due to their racist, gendered, or hurtful language or gendered meanings. We will follow suit, avoiding any racial, gendered, or generalized and hurtful terms. Learn more about these specific terms in the content style and editorial guide.
Disabled, handicapped, impaired
Elderly, senior citizen
Gender and sexuality
Identity-based language
People-first language
Racist language
The Massachusetts Office on Disability (MOD) offers accessibility consulting to Commonwealth agencies. This includes testing accessibility of electronic documents, trainings, websites, and software.
Was this article helpful?
Last updated
