Table of Contents
Content Style Guide
A consistent writing style will help our content feel unified and aid in comprehension.
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.
- Short: Attention spans are limited. Aim for brief, succinct post lengths.
- Focused: Keep it digestible and to a single topic. Posts that span multiple areas and topics should be broken up.
- Accessible: Use plain language and avoid jargon if possible. Explain complicated concepts by breaking them down.
We prefer an active tone, where the subject of the sentence performs the action.
Do: Some people navigate via keyboard.
Don't: It was discovered earlier that some people navigate using keyboard input.
Use American English spelling, unless quoting in context.
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.
- Use complete sentences.
- Use exclamation points sparingly.
- Avoid rhetorical questions.
- Avoid trailing thoughts/ellipses.
- Avoid comma splices, em dash phrases, and semicolons. Using them increases the cognitive load when parsing the sentence.
- Use parentheses with care.
- Use bold and italic text styling sparingly, and when semantically appropriate. Long sections of text set with these text styles have been known to be a Dyslexia trigger.
- Do not underline text. Underlined text should be reserved for links.
- Avoid writing in all caps. Some assistive technologies will announce words set in all caps as individual letters.
- Capitalize words in a hashtag (e.g. #ThisReadsWell).
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.
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".
Do: Some people prefer a large font size.
Don't: Most users have smartphones.
Spell out an acronym in full before using the shorthand version, and wrap each usage of the acronym in the
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.
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.
Use "they" when discussing a person unless they have made their pronouns publicly known.
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.
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.
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.
- Autistic Hoya: Ableism/Language
- Guidelines for Writing About People With Disabilities
- Choosing Words for Talking About Disability - American Psychological Association
- Introduction to Disability Terminology - Disability in Kidlit
- Conscious Style Guide
- The Dos and Don’ts of Writing About the Disabled | Literary Hub
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.
Don't use profane terms unless quoting in context.
Do: Our project manager said, "Ugh, accessibility. Not that shit again." Reader, it was time to act.
Don't: Writing transcripts is fucking tedious.
- Ensure interactive multimedia can be fully operated by keyboard input.
- Multimedia should be able to be paused, and should load in a paused state.
- Don't use multimedia that will automatically steal keyboard focus.
- Multimedia with audio should provide both subtitles and transcripts of any spoken dialog or important sounds.
- Don't use multimedia that uses rapidly blinking, flashing, or strobing content. This may trigger photosensitive seizure disorders.
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.
The A11Y Project uses GitHub-flavored Markdown.
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.
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.
- Use ordered headings to provide a meaningful high-level outline of your content.
- There should be only one first-level heading per page. Blog posts don't need first level headings, as Eleventy will automatically convert the title section of your post's front matter into a first-level heading.
- Blog posts should use pound/hash signs (
#), not underlines (
===) to designate headings.
- For non-blog post content, use heading elements (e.g.
- Use sentence case for headings (e.g. Don't auto-play video, music and more).
- Try to not use headings level 4 through 6. If your content is that detailed, it may need to be broken into separate posts.
- Try to keep your paragraphs on the shorter side. 4 to 5 sentences maximum.
- Don't indent your first paragraph with space characters (e.g.
⋅⋅⋅Three spaces before a paragraph will indent it.).
- Put a period at the end of every list item.
- Uses dashes (
-) for unordered lists.
- Use the number one (
1.) for ordered lists.
- Use one space after a list item.
- Indent nested lists with four spaces (e.g.
- Links should provide context for the content they link to. Avoid using ambiguous terms like "click here".
- Use Markdown-style links (
[link text](URL)) instead of HTML for post content.
- Links should not open in new tabs or windows.
- Use Markdown-style images (
![alternate description](image url)) instead of HTML for post content.
- Provide meaningful alternative (alt) descriptions for images. Alt descriptions should concisely describe the image's content.
- Use complete sentences for your alt descriptions (e.g.
![A happy-looking Labrador Retriever puppy sitting in a clay flower pot.](image url)). Including punctuation in your alt description will help some assistive technology pronounce it clearly.
- Do not use ambiguous terms like "image", "ScreenCapture at Wed Aug 22", "post image", etc.
- Do not use
- Use single backticks to enclose inline code for post content (e.g. The
`footer`element typically contains metadata about its section.).
- Use triple backticks (
```) before and after a multi-line block of code for post content.
- Do not use multi-line blocks of code to create diagrams, flowcharts, or other illustrations.
- Use three hyphens (
---) to create a horizontal rule for post content.
- Use horizontal rules for breaks in paragraph content
- Use horizontal rules for thematic breaks, and not for decoration.
Use HTML only when Markdown cannot accurately describe your post content. Use relevant, semantic HTML elements and attributes. Examples of this would be:
- A video embed.
- A definition list.
- Elements like
<samp>, which do not have Markdown equivalents.
The A11Y Project
This website's name is spelled with a capital T, A, Y, and P.
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" 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.
Do: "The number of developers interested in accessibility a11y (accessibility) is rising quickly."
Don't: When we talk about a11y, we are discussing...
Capitalize the terms critical to using GitHub:
- Pull Request
People, organizations, titles, and honorifics
Honor how someone or something chooses to officially spell their name.
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.
- Cascading Style Sheets (CSS)
- Document Object Model (DOM)
- High Contrast Mode
- Hypertext Markup Language (HTML)
- Scalable Vector Graphics (SVG)
- Web Accessibility Initiative Accessible Rich Internet Applications (WAI-ARIA/ARIA)
- World Wide Web Consortium (W3C)
- Web Content Accessibility Guidelines (WCAG)
- YAML (YAML Ain't Markup Language)