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.
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.
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,
- Add a note explaining that the developer needs to include accessibility features.
- 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.
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 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.