Silver > Clear Language > Edit Text for Clear Language

Edit Text for Clear Language

Edit your text content so that it follows the principles of clear language.

This method contains helpful information, but is not required (informative).

Basics

Status

Platform

This Method applies to all platforms. Its purpose is to improve the accessibility of text content, particularly instructional content or long text content.

Programming Language

Does not apply

How It Solves User Need

This method addresses a number of user needs for people with a variety of cognitive disabilities. Much of it follows general principles of good writing. It includes some of the principles of plain language. It provides a variety of techniquest that when used together makes text content easier to read for all users, but especially for people with disabilities that affect reading comprehension.

Related Guidelines

Detailed Description

  1. Use proper grammar for the language, as defined by a style guide or by standard language rules
  2. Use correct spelling
  3. Use active voice. Active Voice: The subject of the sentence performs the action (verb). Example: Bob paints the house. Passive Voice: The subject of the sentence is acted upon by the verb. Example: The house is painted by Bob.
  4. Use simple verb tense, such as “Bob paints the house”, or “Paint the house.” Do not use perfect or continuous tenses unless needed for accuracy. Simple tense verbs describe actions without stating whether the action is completed or ongoing. Example: Bob paints the house. Perfect Tense verbs describe actions that started in the past and continues into the present. Example: Bob has painted the house. Continuous Tense verbs describe actions that are currently happening."Bob is painting the house."
  5. Use literal and concrete language. When possible, use concrete terms and examples that refer to objects or events that you can see, hear or touch.
  6. Metaphors and similes should not be used unless they are explained.
  7. Limit use of metaphor, similes, sarcasm, or irony. Using words to mean something different or opposite of their literal meaning is confusing to people with some cognitive disabilities.
  8. Use common words or terms to represent concepts where it makes sense. When uncommon words are necessary, define them in context.
  9. Remove unnecessary words such as:
    • Excessive detail (without a summary or heading structure)
    • Extra words that don’t add meaning, such as: "It is cold" vs. "It is really cold"; "First" vs "First and Foremost"; "Each" vs. "Each and every"
  10. Avoid the following when possible. Define or spell out any you use in context:
    • Technical terms
    • Jargon
    • Idioms
    • Slang
    • Acronyms
    • Abbreviations
  11. Break text into sections and provide headings. See the guideline on headings and the guideline on white space (to be written).
  12. Keep sentences and paragraphs short.
  13. Number sequential steps.
  14. Provide brief summaries at the top of long documents.

Related Methods

Not a link to every other method for the guideline, but a link to the Methods that it would also need: For example, an accessible modal would have related methods for keyboard accessibility, disabling interaction with the background, providing a close button, etc.

Code Samples

See the Method (TBD) for define terms in one click.

Tests

You can evaluate this method using one of the three options below. Any one is sufficient.

  1. You can use a professional editor to evaluate the content against the following rubric and implement the recommended changes.
  2. You can develop and use a style guide to your organizations specific needs that implements the following rubric and then test against the style guide.
  3. You can use the following testing rubric.

Rubric for evaluating clear language

Rate each of the areas by:

Action Substantially = 1 Partially = .5 Limited = 0
Use proper grammar for the language, as defined by a style guide or by standard language rules Passes a grammar checker. Errors improve clarity. Some errors Little to no effort has been made.
Use correct spelling Passes a spellchecker. Context errors (false positives and negatives) are corrected Passes a spellchecker, but there are context errors Uncorrected spellchecker errors
Use active voice.
  • Active Voice: The subject of the sentence performs the action (verb).
  • Example: Bob paints the house.
  • Passive Voice: The subject of the sentence is acted upon by the verb.
  • Example: The house is painted by Bob.
No passive voice, or passive voice only where it improves clarity Occasional use of passive voice. Most sentences have passive voice.
Use simple verb tense, such as “Bob paints the house”, or “Paint the house.” Do not use perfect or continuous tenses unless needed for accuracy.
  • Simple tense verbs describe actions without stating whether the action is completed or ongoing.
  • Example: Bob paints the house.
  • Perfect Tense verbs describe actions that started in the past and continues into the present.
  • Example: Bob has painted the house.
  • Continuous Tense verbs describe actions that are currently happening.
  • Example: Bob is painting the house.
Verb tense is consistent and appropriate for the content. Verb tense has some inconsistencies or incorrect tense, but content is still understandable Content is difficult to understand because mixed verb tenses or perfect or continuous tenses are used.
Use literal and concrete language. When possible, use concrete terms and examples that refer to objects or events that you can see, hear or touch. Metaphors and similes should not be used unless they are explained. No figurative or abstract language is used. Uses some figurative or abstract language is used, but content is still understandable Content is difficult to understand because figurative or abstract language is used.
Limit use of metaphor, similes, sarcasm, or irony. Using words to mean something different or opposite of their literal meaning is confusing to people with some cognitive disabilities. No metaphor or sarcasm used. Uses some metaphor or sarcasm, but includes context to aid understanding Uses abstract metaphor, like “getting cold feet” without context to aid understanding
Use common words or terms to represent concepts where it makes sense. When uncommon words are necessary, define them in context. A common words list has been used where it makes sense. Some uncommon words have been used but the content is still understandable. Unnecessary uncommon words have been used or necessary uncommon words are not defined.
Remove unnecessary words such as:
  • Excessive detail (without a summary or heading structure)
  • Extra words that don’t add meaning
  • It is cold vs. it is really cold
  • First vs First and Foremost
  • Each vs. Each and every
Text is concise and understandable. Detailed information has a summary or a heading structure to make it easy to skim. Text has some extra words, but is still understandable. Text contains extra words that make it difficult to understand the content.
Avoid the following when possible. Define or spell out any you use in context:
  • Technical terms
  • Jargon
  • Idioms
  • Slang
  • Acronyms
  • Abbreviations
One of the following is true:
  1. No technical terms, jargon, idioms, etc. are used.
  2. Definitions are provided in context or are one click away and one click to return.
One of the following is true:
  1. Uses some technical terms, jargon, idioms, etc. but don’t always provide definitions and context to aid understanding.
  2. Definitions are provided but the user must search for them or locate them in a glossary.
Uses technical terms, jargon, idioms, etc terms without definitions.
Break text into sections and provide headings. See the guideline on headings and the guideline on white space (to be written). Text is consistently broken into sections with headings. Some of the text is broken into sections with headings, but not consistently. Text is not broken into sections or headings are not used.
Keep sentences and paragraphs short. Sentences and paragraphs are short. Most sentences and paragraphs are short. Content is difficult to understand because sentences and paragraphs are too long.
Number sequential steps. Sequential steps are organized logically and numbered appropriately Sequential steps are organized logically but not numbered Sequential steps are not organized logically nor numbered
Provide brief summaries at the top of long documents. A brief summary that describes the document content is provided. A summary is not provided but another means of aiding understanding is available. No summary is provided or alternative is available.
Provide words and numeric symbols for numbers. Explain numeric concepts in simple words. See the guideline on numbers (to be developed). Be aware that other cultures may have a different meaning for symbols. Numbers and numeric concepts have text and symbol alternatives Some numbers and numeric concepts do not have symbol alternatives, but content is understandable No text or symbol alternatives are provided for numeric concepts
Provide alternatives or explanations for symbols and icons. See the guideline on alternative text for icons. See the guideline for adding symbols, icons, tables, and graphs. (TBD) Text alternatives or explanations are available for symbols and icons Some icons or symbols do not have text alternatives but content is understandable Symbols and icons do not have text alternatives or explanations

Resources

Edit Text for Clear Language

Resource Name
Description

Changelog

None. This is a new Method.

To be done (TBD) for the next working draft (WD):