Skip to content.
Table of Contents

Content Style Guide

A consistent writing style will help our content feel unified and aid in comprehension.

Please check our Code of Conduct and Contributing Guidelines before submitting. Questions or concerns about the Content Style Guide can be addressed in the site's Issue Tracker.

General approach

The A11Y Project follows the latest edition of The Chicago Manual of Style for any grammar and style considerations that aren’t already covered here.

Themes

Tone

We prefer an active tone, where the subject of the sentence performs the action.

Example

Do: Some people navigate via keyboard.

Don't: It was discovered earlier that some people navigate using keyboard input.

Authoring

Written language

Use American English spelling, unless quoting in context.

Example

Do: color

Don't: colour

Reading level

Try not to exceed a seventh grade reading level. Avoid unnecessary jargon and extended metaphors. There are resources that can help you calculate how complex your writing is.

Punctuation

Styling

Capitalization

Concepts and terminology

If possible, link to supporting articles when discussing new concepts and terminology, preferably sites with good accessibility support. This provides the reader with more detail on the subject without having to extend your post's length. It is also provides an alternate way of understanding the subject you introduce.

Avoid analogies, similes, and metaphors that are too reliant on demographic, geography, religion, or culture.

Example

Responsive Web Design (RWD) allows us to create flexible, accessible layouts. Content in RWD behaves like water, fitting whatever container it is placed in.

User or person?

Prefer the terms "person" or "people" over "user" or "users".

Example

Do: Some people prefer a large font size.

Don't: Most users have smartphones.

Acronyms

Spell out an acronym in full before using the shorthand version, and wrap each usage of the acronym in the <abbr> element.

Example

A User Interface (UI) is the space where interaction between humans and machines occur. The goal of a UI is to make it easy, efficient, and enjoyable to operate a machine.

Assumptive phrases

The reader may have a different level of experience than you on the topic you're writing about. Avoid using terms like "just", "simply", "easily", "obviously", etc.

If you make a statement about how a population behaves, please also make sure to cite a trustworthy source.

Gender

Use "they" when discussing a person unless they have made their pronouns publicly known.

Identity

Use the terminology an individual chooses to self-identify with. Prefer identity-first language if it does not conflict with an individual's expressed preferences.

Job titles

Use the lowercase form of a job title or role unless it is in front of a name.

Do: The A11Y Project is run with the help of its maintainers.

Don't: The Senior Developer scoffed at the plumber, thinking he could do better.

Ableist language

Avoid using ableist language, unless quoting in context. Ableist language uses words or phrases that have a negative connotation for disabled people.

Don't describe a person as having a disability unless it is relevant to the point you are trying to make.

Further reading

Examples

Do: This seems confusing!

Don't: This is crazy!

Do: They use a wheelchair.

Don't: They're bound to a wheelchair.

Do: Alice is blind.

Don't: She's handicapable.

Do: They do not have a disability.

Don't: They're able-bodied.

Profanity

Don't use profane terms unless quoting in context.

Example

Do: Our project manager said, "Ugh, accessibility. Not that shit again." Reader, it was time to act.

Don't: Writing transcripts is fucking tedious.

Multimedia

Spell-check

Please check your spelling before submitting content. Many code editors have spell checking extensions. This is a courtesy to both your readers and the people who will review your contribution.

Markdown

The A11Y Project uses GitHub-flavored Markdown.

Front matter

Eleventy uses front matter information to create things like author attribution, categories, and page layout.

Copying an existing file, then updating its filename and front matter to can be an easy way to help ensure everything is formatted properly.

Line breaks

Use a single newline to separate block-level content like headings, lists, images, code blocks, etc. The exception is second-level headings, where it should be two newlines. This helps visualize the overall structure of content in a code editor.

Headings

Further reading

How-to: Accessible heading structure

Paragraphs

Lists

Images

Code

Horizontal rules

Inline HTML

Use HTML only when Markdown cannot accurately describe your post content. Use relevant, semantic HTML elements and attributes. Examples of this would be:

Important terms

The A11Y Project

This website's name is spelled with a capital T, A, Y, and P.

Example

Do: The A11Y Project

Don't: a11y Project

The A11Y Project also uses the following terms as proper nouns when discussing accessibility-related content:

a11y/accessibility

"a11y" is a numeronym that is short for "accessibility". The number 11 stands for the 11 letters between the first and last letters of the word.

The numeronym is to not be used in formal writing. Use the full word, unless quoting in context.

Example

Do: "The number of developers interested in accessibility a11y (accessibility) is rising quickly."

Don't: When we talk about a11y, we are discussing...

GitHub

Capitalize the terms critical to using GitHub:

People, organizations, titles, and honorifics

Honor how someone or something chooses to officially spell their name.

Example

danah boyd is a technology and social media scholar. She is a Principal Researcher at Microsoft Research, the founder and president of Data & Society Research Institute, and a Visiting Professor at New York University.

Other proper nouns

These terms are commonly used on the site, or in the accessibility community.