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

• 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.

Tone

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

Example

Authoring

Written language

Use American English spelling, unless quoting in context.

Example

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

• 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.

Styling

• 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.

Capitalization

• 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.

Example

User or person?

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

Example

Acronyms

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

Example

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.

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

• 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

Examples

Profanity

Don't use profane terms unless quoting in context.

Example

Multimedia

• 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.

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

• 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 (--- or ===) to designate headings.
• For non-blog post content, use heading elements (e.g. <h2>).
• 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.

Further reading

How-to: Accessible heading structure

Paragraphs

• 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.).

Lists

• 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

• 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.

Images

• 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 height and width attributes.

Code

• 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.

Horizontal rules

• 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.

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:

• A video embed.
• A definition list.
• Elements like <kbd> and <samp>, which do not have Markdown equivalents.

Important terms

The A11Y Project

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

Example

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

• How-tos
• Myths

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

GitHub

Capitalize the terms critical to using GitHub:

• Branch
• Clone
• Fork
• Git
• Issue
• Pull Request
• Release

People, organizations, titles, and honorifics

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

Example

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)
• JavaScript (JS)
• JavaScript Object Notation (JSON)
• Landmark
• Meetup
• Scalable Vector Graphics (SVG)
• Web Accessibility Initiative Accessible Rich Internet Applications (WAI-ARIA/ARIA)
• World Wide Web Consortium (W3C)
• Web Content Accessibility Guidelines (WCAG)
• Webinar
• YAML (YAML Ain't Markup Language)