Any piece of written content we produce should be readily understandable by people with many different abilities, levels of education and cultural backgrounds. The most important step toward that goal is clarity of thought – clarity of writing usually follows. When you know what you want to say, you’ll have no trouble saying it clearly.
This document collects some guidelines on technical aspects of writing that sometimes get in the way of understanding, like spelling, abbreviations and date formats. They’ll get you out of a tricky situation every once in a while, but they are no subsitute for clarity of thought.
In addition to generally being a good idea, understandable writing is also an important element of the Web Content Accessibility Guidelines (WCAG), a widely-accepted accessibilty standard we aim to follow. Many of the guidelines below directly correspond to success criteria of the WCAG. Where this is the case, we’ve linked to the relevant section for context.
This guide is a living document. If you have ideas for improvements, please share them at [email protected].
We’re called Neurodiversity in Albertopolis. The abbreviation is NDIA (all uppercase). See also Abbreviations.
- Use plain language and avoid figures of speech, idioms, foreign phrases, and complicated metaphors. See WCAG 3.1.5.
- Use the active voice whenever you can.
- For spelling follow the Oxford English Dictionary, except for proper names like Center for Disease Control and Prevention.
- Make sure that link text is unique and descriptive. Terms like click here and read more do not provide any context and should be avoided. Do: The British Dyslexia Association is the voice of dyslexic people. Don’t: The British Dyslexia Association is the voice of dyslexic people, read more about them here. See WCAG 1.3.1.
- Use real headlines.
h1is reserved for the title of the site. The title of a page (like this one) is an
h2.This gives you
h6to work with to structure your writing.
- Use bold text for emphasis instead of italics or ALL-CAPS, which are harder to read. Underlined text is reserved for links.
The best way to make abbreviations understandable is to avoid them altogether. Either spell out the abbreviated term in full (Royal College of Art instead of RCA), or replace the acronym with a plain language description of the concept (college management instead of SMT).
If you need to use an abbreviation, expand it when it first appears. For example: Neurodiversity in Albertopolis (NDIA) was founded in 2019. After that, you can use the abbreviation without further explanation.
Very common abbreviations like Mr, Mrs, am, pm, etc, UK, and US are okay without explanation.
See WCAG 3.1.4.
Dates and Times
People are used to many different date formats. To avoid any confusion, write dates in the format Day Month, Year using the full name of the month. For example: 28 June, 2021. Give times of day in 24-hour format without leading zeros, as in 9:30 and 17:00.
Every image that isn’t purely decorative must have an alt text (shortened from alternative text) to make it accessible to people using assistive technology. The alt text is a short visual description that gives a general sense of the content of an image.
- Write in the simple present.
- Aim for a length of 15-20 words.
- The alt text contains no period at the end unless it is a complete sentence.
- If the image contains text, transcribe it in full in the alt text.
You can add alt text to images in WordPress through the upload dialogue, the media library, or the block editor. Once you’ve entered the alt text, it will be included automatically whenever the image appears.
For further reading on image descriptions, take a look at the Cooper Hewitt Guidelines for Image Description.
See WCAG 1.1