General Writing Guidelines
General User Experience (UX) writing guidelines
Audience first: Focus on client needs, not business needs. Is the information geared to the right audience? Are you using the language the client uses, and avoiding internal jargon? Content written by subject matter experts may need to be edited. Does the content organization reflect where your reader would intuitively look for it, or are you organizing your content according to your internal business structure?
Consistency: Consistency is important for all users, and is a requirement to meet ADA/WCAG accessibility standards. This applies to both wording and visual design. Repeated patterns help users find content quickly and understand the relationships between similar items.
Be specific: Avoid broad labels like “miscellaneous”, “general”, etc. Group related items together and be as specific as possible in naming their category, using commonly understood labels. Avoid creating a content “junk drawer” for items that don’t seem to fit anywhere. Miscellaneous categories that are a collection of unrelated material make content hard to find.
Content models: Look at similar pages for opportunities to create content models that format like-content consistently (a “template” for organizing content). Your site already has some content models, such as events listings.
Site depth: Keep the number of clicks that a user has to perform to a minimum – don’t send the reader down multiple levels/paths to get to what they’re looking for. Make sure they can easily get back to where they started.
Content hierarchy: The most important information should be “above the fold”. Don’t hide vital information at the bottom of the page, or in an FAQ. If something is being asked frequently, it probably means it’s important information that the reader is looking for. If it’s not tangential to the main focus of the page, it probably should be surfaced.
Front Loading: Putting the most important words at the beginning of a sentence, headline, or other element helps users scan content quickly. Examples include SEO keywords, verbs, or words that distinguish two or more items from one another. When actions are required, using the format “to do x, do y” is helpful.
For example, “To complete your registration, call 1-800-321-5639” is easier for a screen reader user than “Call 1-800-321-5639 to complete your registration”. The first example uses the “to do x, do y” order. This sentence structure lets the reader: decide early whether they need to finish the sentence, or devote energy to remembering the number; and if it’s the number they need, they can act on it immediately, before they forget (or if linked, they can activate it directly without having to go back to find it).
Plain Language
We communicate in plain language, using simple, straightforward language and avoiding jargon and needless complexity. This makes us more engaging, welcoming, and approachable. Plain language means we write for our audiences, using easy-to-understand words and sentence structure. More importantly, it’s vital for accessibility.
As well as helping to meet ADA requirements, plain language has additional advantages:
Efficiency: Follow plain language principles to help the widest audience understand your message, and also help all readers quickly find what they’re looking for.
Globalization: Plain language is more understandable by people who speak English as a second language, and is easier to translate.
Mobile friendly: Plain language is generally shorter, so content fits more easily on mobile devices.
Search: Plain language is important for internal and external search, including voice search. Use the language your audience uses.
Plain language key takeaways
Short sentences
Straightforward grammar
Active vs. passive voice
One instruction per sentence
Simple, everyday words
Elimination of jargon
Bullet points when possible
Grade 8 reading level or lower
We speak in the active voice for more clarity, energy, and confidence.
We speak in first person plural, using we, us, our, and ours.
This makes us more inclusive and welcoming. It keeps our audiences involved and engaged. This connection helps make our network strong and connects us to our members.
Sort order
When sorting content, use sub-heads to organize and easily identify related content. If content relates to actions that should be taken in a particular order, you may want to sort links and blocks of content in the order the content is needed by your site users. Otherwise, a common sorting strategy is alphabetical order.
Key considerations when sorting content
Sorting by alphabetical order is a valuable and intuitive way to organize large numbers of items. However, there are some things to consider:
Items should be in the same category
High-level categories such as landing pages are usually determined by their importance to your audience. Secondary content under a category can be presented alphabetically.
Long lists of alphabetical links should either be grouped into related categories with subheads, or use an A-Z glossary-style component that provides shortcuts to letter groupings.
If last name is hyphenated, alphabetize using first part of the hyphenated last name. Examples: Susan Smith Jones is placed under "J", but Susan Smith-Jones is placed under "S".
Avoid repetition: Front-load list items with unique, descriptive keywords at the beginning of the list item; avoid repeating words at the beginning of multiple items. Readers scan alphabetical lists to find what they’re looking for, so this makes it easier and faster to locate the right item. Remove the repeated word from list items (for example, “Department of…”).
There are a number of common patterns (often found in older site content) that, if eliminated, will help to reduce word counts and page counts, improve site architecture and page organization, make content easier to find and scan, make content easier to manage in the CMS, and create useful, findable and actionable information.
Avoid:
Pages with single links, or only 2 or 3 links, with little or no other content. This causes unnecessary steps to get to content, and sometimes creates a forking of the user journey. For example, after following a link down one path the user can’t get back to the original page, or they forget there is more information related to the topic. Generally, pages that have a small number of links and no other content can be combined into a single page.
Pages with many links and no categorization: this requires the reader to spend time scanning through all the links to find what they’re looking for.
Low-content pages: Pages with low word counts (generally under 200 words) create site bloat, and cause unnecessary work for the reader to find information. It may negatively affect SEO, as search engines need a certain amount of content to determine the purpose of the page. This content can usually be combined with related content onto a single page.
Duplicate content: The same or very similar content in more than one place causes confusion for the reader, can easily get out of sync if one page is updated and not another, and can negatively affect your SEO page rankings. It can also sometimes cause confusion for blind users relying on screen readers. Short pieces of content can be reused if it exists in a single location in the CMS (“write once, publish anywhere”) but content shouldn’t be cut and pasted into more than one location, and duplicate pages should always be eliminated.
Pages that rely on site architecture to fill in the blanks: Readers might get to a page from a variety of paths. Make sure the content on the page has enough context and makes sense no matter how the reader arrives there; don’t rely on them having read the previous landing page or other specific pages beforehand.
Over-reliance on visual elements: A blind or visually impaired user may be using a screen reader to listen to content, or a screen magnifier that only shows a part of the page, and therefore can’t see the visual cues. If you stripped out all the graphics from a page and are left with text only, does everything still make sense, or do you need to fill in some gaps?
Multi-language considerations
For translated content, it’s beneficial to optimize the English content first with plain language in mind. This will reduce ambiguity and make translations easier. The general formatting of translated content should align as closely as possible with the English copy e.g. subheads, bulleted lists, numbering, etc.
Some things to consider for a site with multi-language content:
Beware of idioms and jargon that may not work in other cultures.
Currency figures, accents and punctuation differ between many languages. For example, French has many accents, while English generally only uses them in foreign words; French also places the dollar symbol after numbers instead of before, as in English.
Word counts: Languages like Spanish and French can be up to 30% longer than English, and German can be more than 200% longer. Start short with the English content to allow for the extra space required by your translated language. Plain language in your English content can keep word counts down to allow for extra space needed for the translation.
Language toggles: For links to switch between languages, the language names should be spelled out in full, rather than using abbreviations e.g. “English”, “Français” and “Espanol”, not EN, FR and ES. The exception to abbreviations is in URLs and back-end language tags which use two-letter codes. Make sure the language toggle is in the same language as the destination page, not the language of the page the visitor is currently on. For example, on an English page the language toggle should say “Espanol” for a Spanish audience (Not “Spanish”). Pay extra attention to the second-language page that links back to English, as this is commonly where mistakes happen.
Additional multi-language takeaways
Visually impaired site visitors rely on screen readers to announce the content; they can’t see a sudden switch in languages, so need the change announced beforehand. As well, the screen reader technology needs to know the language that content is written in so that the content can be pronounced correctly.
It’s best to have unique copies of pages for each language, and tag them with the proper language tag.
Avoid mixing multiple languages on the same page. If you must include content in more than one language on a single page, each section of content has to be tagged to identify the language of that section so the screen reader can correctly announce the change and pronounce the content correctly. This tagging may or may not be possible depending on your CMS, which is why it’s preferable to separate the languages on unique pages that can be identified in their URLs..
Beware of machine translation. There isn’t a one-to-one translation between languages, and mistakes often happen. Use a human translator, or if you need to start with machine translation, make sure the content is reviewed and edited by a native speaker to avoid potential errors that could harm your brand.
As well as the differences in word counts, punctuation and accents mentioned above, as with Spanish, there are different versions of French, depending on where speakers reside. While French is a global language, two main distinct variations are European French and “Canadian” French. In Canada there are actually variations in different regions of the country, but since the most common is that spoken in Quebec, so we refer to it as “Quebecois” French.
European and Canadian French have significant differences between them, including vocabulary, idioms, slang, and cultural meaning, as well as pronunciation. Canadian/Quebecois French is often generally less formal than European French. It’s important to use the variant that fits your target audience. If both are needed, use native speakers to edit the content. You’ll also need to distinguish between them in your language toggles and any other language tags.