Inclusion and accessibility

Inclusion and accessibility

web.dev has a large international audience. We want members of that audience to access and understand web.dev content, and they should feel included in the ways we speak to our readers.

Use readable language

Aim for a grade 8 reading level when possible. If you don't have a feel for what grade 8 texts look like, check out some examples on Newsela. You can also run your text through a readability test.

It can be difficult to write technical content for a grade 8 reading level. The following guidelines help keep your language as accessible as it can be.

Write shorter, simpler sentences.

Don't

We also include an HTML table of buttons for accessibility reasons that is on top of the canvases but is made invisible using opacity: 0.

Do

We also include an HTML table of buttons to improve accessibility. The table sits on top of the canvases and is made invisible using opacity: 0.

Use commonly used words that your audience is likely to be familiar with instead of specialized vocabulary. If you need help finding a more accessible alternative, the Merriam-Webster Learner's Dictionary is a handy tool.

Don't

In some scripts, graphemes can be visually joined when they're adjacent.

Script and grapheme are very precise, but they're likely to be unfamiliar to most readers and may cause confusion since readers probably more commonly see script referring to a piece of code.

Do

In some written languages, certain characters can be visually joined when they're adjacent.

While written language and character are slightly less precise, they should be more familiar and less likely to cause misunderstandings.

If you must use a word that your audience is unlikely to know, provide a definition using the Key-term Aside component.

Make information easy to find

Don't skip heading levels. Don't add custom styles to headings—it makes the page hierarchy more difficult to follow.

Spell out acronyms the first time they're used. For example: Web Incubation Community Groups (WICG).

Place exceptions, edge cases, and other kinds of supplemental information right next to the primary content they're related to.

Use inclusive images

Always provide alt text.

If you're creating an illustration, the parts that are essential for understanding the illustration should have a contrast ratio of at least 3:1. You can verify the contrast using checkers like the ones from WeAIM or the Paciello Group.

Avoid images that may exclude certain audience members. Just like when you write about people, remember to be inclusive when you show people and the things they do and make. For example, avoid stock photos that show only male developers.

Create accessible code blocks

Make sure code blocks are simple and follow accessibility best practices. At a minimum:

In the rare case that you need to omit an accessibility detail to better convey what you're teaching,

  1. Add a note explaining that the developer needs to include accessibility features.
  2. Link to the relevant post in the web.dev "Accessible to all" collection.

Writing about people

There are several excellent online guides for using inclusive language when writing about groups of people. The Content Guide from 18F (a U.S. government office that helps other agencies improve their user experience) is a great place to start.

To be more gender inclusive, use they/them for singular personal pronouns instead of he/him and she/her. However, it's ideal to make it plural.

Good

If the reader is interested in diving deeper after reading web.dev, they can turn to other sources.

Better

If readers are interested in diving deeper after reading web.dev, they can turn to other sources.

Writing for an international audience

Avoid idioms. If non-native speakers aren't familiar with the idiom, they may be confused. Also, idioms are often lost in translation.

Don't

The sample app should work now. Give it a shot!

Do

The sample app should work now. Try it!

Don't rely on cultural references alone to convey essential information. It's likely that at least some of your audience won't know the same movies, TV, books, and games that you do. While a reference here and there can add personality to your writing, make sure readers can understand your ideas even if they don't catch the reference.

Last updated: Improve article