diff --git a/guidelines/groups/text-and-wording.json b/guidelines/groups/text-and-wording.json index 67ad6915..c7eb2b83 100644 --- a/guidelines/groups/text-and-wording.json +++ b/guidelines/groups/text-and-wording.json @@ -2,7 +2,6 @@ "children": [ "text-appearance", "text-to-speech", - "clear-meaning", - "simplified-written-content" + "clear-language" ] } diff --git a/guidelines/groups/text-and-wording/clear-language.md b/guidelines/groups/text-and-wording/clear-language.md new file mode 100644 index 00000000..5cf781da --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language.md @@ -0,0 +1,48 @@ +--- +children: + - clear-structure + - short-blocks-of-text + - sentence-structure + - common-words + - abbreviations + - non-literal-language + - verb-tense + - numerical-supplements + - unambiguous-numerical-formatting + - visual-aids + - summaries + - topic-sentence + - unambiguous-pronunciation + - review-process + - style-guide + - training-policy +status: developing +--- + +Users can understand the content without having to process complex or unclear language. + +:::ednote +This guideline will include exceptions for poetic, scriptural, artistic, and other content whose main goal is expressive rather than informative. + +To ensure this guideline works well across different languages, +members of AG, COGA, and internationalization (i18n) agreed on an initial set of languages to pressure-test the guidance. +The five "guardrail" languages are: + +- Arabic +- English +- Hindi +- Mandarin +- Russian + +We started with the six official languages of the United Nations (UN). Then we removed French and Spanish because they are similar to English. We added Hindi because it is the most commonly spoken language that is not on the UN list. + +The group of five languages includes a wide variety of language features, such as: + +- Right-to-left text layout +- Vertical text layout +- Tonal sounds that affect meaning + +This list doesn't include every language, but it helps keep the work manageable while making the guidance more useful for a wide audience. +We will work with W3C’s Global Inclusion community group, the Internationalization (i18n) task force, and others to review and refine the testing and techniques for these requirements. +We also plan to create guidance for translating the guidelines into more languages in the future. +::: diff --git a/guidelines/groups/text-and-wording/clear-language/abbreviations.md b/guidelines/groups/text-and-wording/clear-language/abbreviations.md new file mode 100644 index 00000000..69108baa --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/abbreviations.md @@ -0,0 +1,6 @@ +--- +status: developing +type: foundational +--- + +Explanations are available for the first use of abbreviations, acronyms, initialisms, and numeronyms. diff --git a/guidelines/groups/text-and-wording/clear-language/clear-structure.md b/guidelines/groups/text-and-wording/clear-language/clear-structure.md new file mode 100644 index 00000000..e2098750 --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/clear-structure.md @@ -0,0 +1,6 @@ +--- +status: developing +type: foundational +--- + +Content has a meaningful and understandable structure that clearly indicates the purpose of each section. diff --git a/guidelines/groups/text-and-wording/clear-language/common-words.md b/guidelines/groups/text-and-wording/clear-language/common-words.md new file mode 100644 index 00000000..aacdc168 --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/common-words.md @@ -0,0 +1,10 @@ +--- +status: developing +type: foundational +--- + +Common words are used, and definitions are available for uncommon words that the target audience is unlikely to know. + +:::ednote +This requirement will include tests and techniques for content that is intended for specialized audiences rather than the general public. +::: diff --git a/guidelines/groups/text-and-wording/clear-language/non-literal-language.md b/guidelines/groups/text-and-wording/clear-language/non-literal-language.md new file mode 100644 index 00000000..c3731ddf --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/non-literal-language.md @@ -0,0 +1,7 @@ +--- +status: developing +title: Non-literal language +type: foundational +--- + +Explanations or unambiguous alternatives are available for :term[non-literal language], such as idioms and metaphors. diff --git a/guidelines/groups/text-and-wording/clear-language/numerical-supplements.md b/guidelines/groups/text-and-wording/clear-language/numerical-supplements.md new file mode 100644 index 00000000..63d4e727 --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/numerical-supplements.md @@ -0,0 +1,6 @@ +--- +status: developing +type: foundational +--- + +Alternatives are provided for numbers and numerical concepts. diff --git a/guidelines/groups/text-and-wording/clear-language/review-process.md b/guidelines/groups/text-and-wording/clear-language/review-process.md new file mode 100644 index 00000000..5ce1c163 --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/review-process.md @@ -0,0 +1,7 @@ +--- +status: developing +type: assertion +--- + +- The organization has a documented process to review content for clear language before publication. +- If the organization uses AI tools to generate or alter content, the organization has a documented process for a human to review and attest that the content is clear and conveys the intended meaning. diff --git a/guidelines/groups/text-and-wording/clear-language/sentence-structure.md b/guidelines/groups/text-and-wording/clear-language/sentence-structure.md new file mode 100644 index 00000000..56dd6502 --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/sentence-structure.md @@ -0,0 +1,6 @@ +--- +status: developing +type: foundational +--- + +Sentences are streamlined to avoid unnecessary words or phrases and complex structures such as clauses within clauses that can make it hard for users to focus on the main point. diff --git a/guidelines/groups/text-and-wording/clear-language/short-blocks-of-text.md b/guidelines/groups/text-and-wording/clear-language/short-blocks-of-text.md new file mode 100644 index 00000000..c83ba4eb --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/short-blocks-of-text.md @@ -0,0 +1,6 @@ +--- +status: developing +type: foundational +--- + +Content is organized into short paragraphs or “chunks” to help users understand and remember the information. diff --git a/guidelines/groups/text-and-wording/clear-language/style-guide.md b/guidelines/groups/text-and-wording/clear-language/style-guide.md new file mode 100644 index 00000000..090aa4f2 --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/style-guide.md @@ -0,0 +1,7 @@ +--- +status: developing +type: assertion +--- + +- The organization has a documented style guide that includes guidance on clear language and a policy that requires editors to follow the style guide. +- The style guide includes guidance on clear words as well as clear numbers, such as avoiding or explaining Roman numerals, removing numerical information that is not essential for understanding the content, and providing explanations of essential numerical information to aid users with disabilities that impact cognitive accessibility. diff --git a/guidelines/groups/text-and-wording/clear-language/summaries.md b/guidelines/groups/text-and-wording/clear-language/summaries.md new file mode 100644 index 00000000..d87be509 --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/summaries.md @@ -0,0 +1,6 @@ +--- +status: developing +type: foundational +--- + +A summary is available for documents and articles that have more than 300 words. diff --git a/guidelines/groups/text-and-wording/clear-language/topic-sentence.md b/guidelines/groups/text-and-wording/clear-language/topic-sentence.md new file mode 100644 index 00000000..3c3d9c5e --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/topic-sentence.md @@ -0,0 +1,6 @@ +--- +status: developing +type: supplemental +--- + +For content intended to inform the user, each paragraph begins with a sentence stating the aim or purpose. diff --git a/guidelines/groups/text-and-wording/clear-language/training-policy.md b/guidelines/groups/text-and-wording/clear-language/training-policy.md new file mode 100644 index 00000000..6f866de8 --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/training-policy.md @@ -0,0 +1,6 @@ +--- +status: developing +type: assertion +--- + +- The organization has documented training material for content editors that includes guidance on clear language and a policy that editors are required to complete the training regularly. diff --git a/guidelines/groups/text-and-wording/clear-language/unambiguous-numerical-formatting.md b/guidelines/groups/text-and-wording/clear-language/unambiguous-numerical-formatting.md new file mode 100644 index 00000000..1963ad33 --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/unambiguous-numerical-formatting.md @@ -0,0 +1,6 @@ +--- +status: developing +type: foundational +--- + +Numerical information includes sufficient context to avoid confusion when presenting dates, temperatures, time, and Roman numerals. diff --git a/guidelines/groups/text-and-wording/clear-language/unambiguous-pronunciation.md b/guidelines/groups/text-and-wording/clear-language/unambiguous-pronunciation.md new file mode 100644 index 00000000..104bc5e4 --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/unambiguous-pronunciation.md @@ -0,0 +1,7 @@ +--- +status: developing +type: supplemental +--- + +For Arabic and Hebrew, where letters or diacritics needed for phonetic reading are often omitted, +an alternative version is provided with these missing elements included. diff --git a/guidelines/groups/text-and-wording/simplified-written-content/verb-tense.md b/guidelines/groups/text-and-wording/clear-language/verb-tense.md similarity index 56% rename from guidelines/groups/text-and-wording/simplified-written-content/verb-tense.md rename to guidelines/groups/text-and-wording/clear-language/verb-tense.md index e06633a2..882fe53e 100644 --- a/guidelines/groups/text-and-wording/simplified-written-content/verb-tense.md +++ b/guidelines/groups/text-and-wording/clear-language/verb-tense.md @@ -1,6 +1,6 @@ --- -needsAdditionalResearch: true -status: exploratory +status: developing +type: foundational --- The verb tense used is easiest to understand in context. diff --git a/guidelines/groups/text-and-wording/clear-language/visual-aids.md b/guidelines/groups/text-and-wording/clear-language/visual-aids.md new file mode 100644 index 00000000..1a20193e --- /dev/null +++ b/guidelines/groups/text-and-wording/clear-language/visual-aids.md @@ -0,0 +1,6 @@ +--- +status: developing +type: foundational +--- + +Visual aids are available to supplement and aid understanding of complex ideas in written content, such as processes, workflows, relationships, or chronological information. diff --git a/guidelines/groups/text-and-wording/clear-meaning.md b/guidelines/groups/text-and-wording/clear-meaning.md deleted file mode 100644 index 30236722..00000000 --- a/guidelines/groups/text-and-wording/clear-meaning.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -children: - - detectable-text - - unambiguous-text -status: developing ---- - -Users can access explanations of or alternatives to ambiguous :term[text] :term[content]. - -:::decision-tree -For each item of ambiguous text, such as :term[non-literal text], abbreviations and acronyms, :term[ambiguous numbers], or text missing letters or diacritics: -1. Is the text presented in a way that is available to :term[user agents], including assistive technology (AT)? - - Yes, view meets Text is programmatically determinable, continue. - - No, continue to step 3. -2. Does the :term[accessibility support set] meet Explain ambiguous text or provide an unambiguous alternative? - - Yes, pass. Stop. - - No, continue. -3. Does the author meet Explain ambiguous text or provide an unambiguous alternative? - - Yes, pass. Stop. - - No, fail. - -**Exception** - -- If the purpose is to showcase works of art or fiction, such as a poetry journal or fictional stories, this guideline does not apply. However, if the purpose is to educate students about art or fiction, then this guideline applies. -::: diff --git a/guidelines/groups/text-and-wording/clear-meaning/detectable-text.md b/guidelines/groups/text-and-wording/clear-meaning/detectable-text.md deleted file mode 100644 index 5f404d3a..00000000 --- a/guidelines/groups/text-and-wording/clear-meaning/detectable-text.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -type: foundational ---- - -Text is programmatically determinable. diff --git a/guidelines/groups/text-and-wording/clear-meaning/unambiguous-text.md b/guidelines/groups/text-and-wording/clear-meaning/unambiguous-text.md deleted file mode 100644 index a3a2498b..00000000 --- a/guidelines/groups/text-and-wording/clear-meaning/unambiguous-text.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -type: foundational ---- - -Explain ambiguous text or provide an unambiguous alternative. diff --git a/guidelines/groups/text-and-wording/simplified-written-content.md b/guidelines/groups/text-and-wording/simplified-written-content.md deleted file mode 100644 index ba5436db..00000000 --- a/guidelines/groups/text-and-wording/simplified-written-content.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -children: - - appropriate-tone - - double-negatives - - sentence-voice - - uncommon-words - - unnecessary-words-or-phrases - - verb-tense ---- - -Users are not required to navigate complex words or sentence structures in order to understand :term[content]. diff --git a/guidelines/groups/text-and-wording/simplified-written-content/appropriate-tone.md b/guidelines/groups/text-and-wording/simplified-written-content/appropriate-tone.md deleted file mode 100644 index 4d1324cd..00000000 --- a/guidelines/groups/text-and-wording/simplified-written-content/appropriate-tone.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -needsAdditionalResearch: true -status: exploratory ---- - -The language and tone used is appropriate to the topic or subject matter. diff --git a/guidelines/groups/text-and-wording/simplified-written-content/double-negatives.md b/guidelines/groups/text-and-wording/simplified-written-content/double-negatives.md deleted file mode 100644 index e15f1dc1..00000000 --- a/guidelines/groups/text-and-wording/simplified-written-content/double-negatives.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -status: exploratory ---- - -:term[Content] does not include double negatives to express a positive unless it is standard usage for that language or dialect. diff --git a/guidelines/groups/text-and-wording/simplified-written-content/sentence-voice.md b/guidelines/groups/text-and-wording/simplified-written-content/sentence-voice.md deleted file mode 100644 index 2b1fc9af..00000000 --- a/guidelines/groups/text-and-wording/simplified-written-content/sentence-voice.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -needsAdditionalResearch: true -status: exploratory ---- - -The voice used is easiest to understand in context. diff --git a/guidelines/groups/text-and-wording/simplified-written-content/uncommon-words.md b/guidelines/groups/text-and-wording/simplified-written-content/uncommon-words.md deleted file mode 100644 index 38b6fea7..00000000 --- a/guidelines/groups/text-and-wording/simplified-written-content/uncommon-words.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -needsAdditionalResearch: true -status: exploratory ---- - -Definitions for uncommon or new words are available. diff --git a/guidelines/groups/text-and-wording/simplified-written-content/unnecessary-words-or-phrases.md b/guidelines/groups/text-and-wording/simplified-written-content/unnecessary-words-or-phrases.md deleted file mode 100644 index ff0c2925..00000000 --- a/guidelines/groups/text-and-wording/simplified-written-content/unnecessary-words-or-phrases.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -status: exploratory ---- - -Sentences are concise, without unnecessary filler words and phrases. diff --git a/guidelines/terms/non-literal-language.md b/guidelines/terms/non-literal-language.md new file mode 100644 index 00000000..285e04ee --- /dev/null +++ b/guidelines/terms/non-literal-language.md @@ -0,0 +1,29 @@ +--- +status: developing +title: Non-literal language +--- + +words or phrases used in a way that are beyond their standard or dictionary meaning to express deeper, more complex ideas + +:::note +This is also called figurative language. + +To understand the content, users have to interpret the implied meaning behind the words, rather than just their literal or direct meaning. + +Examples include: + +- allusions +- hyperbole +- idioms +- irony +- jokes +- litotes +- metaphors +- metonymies +- onomatopoeias +- oxymorons +- personification +- puns +- sarcasm +- similes +::: \ No newline at end of file diff --git a/guidelines/terms/non-literal-text.md b/guidelines/terms/non-literal-text.md deleted file mode 100644 index f68fd4c3..00000000 --- a/guidelines/terms/non-literal-text.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -status: developing -title: Non-literal text ---- - -non-literal text uses words or phrases in a way that goes beyond their standard or dictionary meaning to express deeper, more complex ideas - -:::note -This is also called figurative language. - -To understand it, users have to interpret the implied meaning behind the words, rather than just their literal or direct meaning. - -Examples: - -- allusions -- hyperbole -- idioms -- irony -- jokes -- litotes -- metaphors -- metonymies -- onomatopoeias -- oxymorons -- personification -- puns -- sarcasm -- similes - -More detailed examples are available in the :term[Methods] section. -::: \ No newline at end of file diff --git a/guidelines/terms/ambiguous-numbers.md b/guidelines/terms/unambiguous-numerical-formatting.md similarity index 100% rename from guidelines/terms/ambiguous-numbers.md rename to guidelines/terms/unambiguous-numerical-formatting.md