Merge pull request #144 from w3c/How-to-updates-2024-11

How-to updates

guidelines/index.html

@@ -352,13 +352,14 @@ <h4>Clear meaning</h4>
 						<summary>Which foundational provision applies?</summary>
 						<p>For each item of ambiguous text, such as <a>non-literal text</a>, abbreviations and acronyms, <a>ambiguous numbers</a>, or text missing letters or diacritics:</p>
 						<ol>
-							<li>Is the ambiguous text presented in a way that is available to <a>user agents</a>, including assistive technology?
+							<li>Is the text presented in a way that is available to <a>user agents</a>, including assistive technology (AT)?
 								<ul>
 									<li>Yes, view meets <a href="#detectable-text">Text is programmatically determinable</a>, continue. </li>
 									<li>No, continue to step 3. </li>
 								</ul>
 							</li>
-							<li>Does the accessibility support set meet <a href="#unambiguous-text">Explain ambiguous text or provide an unambiguous alternative</a>?
+
+							<li>Does the <a>accessibility support set</a> meet <a href="unambiguous-text">Explain ambiguous text or provide an unambiguous alternative</a>?
 								<ul>
 									<li>Yes, pass. Stop. </li>
 									<li>No, continue. </li>

how-to/outcomes/clear-meaning/index.md

@@ -8,6 +8,14 @@ To help people understand text:
 * Use clear, unambiguous language, or 
 * Explain the implied meaning of ambiguous language.
 
+This guideline covers four types of ambiguous text content:
+* **non-literal text**, such as idioms, metaphors, similes, and sarcasm,
+* **abbreviations or acronyms** that are not defined on first use,
+* **ambiguous numbers**, such as date formatting that can have different meanings in different cultures, and
+* **text that leaves out letters or diacritics** needed to read the words phonetically, such as in Arabic and Hebrew.
+
+For each instance of ambiguous text content, the goal is to ensure clarity and provide necessary context.
+
 Making ambiguous content (including non-literal or figurative language) easier to understand helps people with cognitive disabilities as well as neurodivergent people, such as those who are autistic and may be so focused on the literal meaning that they may not notice the implied meaning.
 
 Explaining or avoiding ambiguous language can also help:
@@ -29,22 +37,22 @@ Explaining or avoiding ambiguous language can also help:
 
 For each item of ambiguous text, such as non-literal text, abbreviations and acronyms, ambiguous numbers, or text missing letters or diacritics:
 
-1. Is the non-literal text presented in a way that is available to user agents, including assistive technology (AT)?
+1. Is the ambiguous text presented in a way that is available to user agents, including assistive technology (AT)?
    1. Yes, view meets *Text is programmatically determinable*, continue.
    2. No, continue to step 3.
-2. Does the *accessibility support set* meet *Explain ambiguous text or provide an unambiguous alternative*?
-   1. Yes, pass.
+2. Does the *accessibility support set* meet [Explain ambiguous text or provide an unambiguous alternative](methods/explain-ambiguous-text/)?
+   1. Yes, pass. Stop.
    2. No, continue. 
-3. Does the publisher sufficiently explain the non-literal text or provide a literal alternative?
-   1. Yes, view meets *Explain non-literal text or provide a literal alternative*, pass.
+3. Does the author meet [Explain ambiguous text or provide an unambiguous alternative](methods/explain-ambiguous-text/)?
+   1. Yes, pass. Stop.
    2. No, fail.
 
 #### Exceptions
 * 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 pieces of art, then this guideline applies.
 
 </div>
 
-### Supplimental Requirements
+### Supplemental Requirements
 
 <p class="ednote">None defined at this time.</p>
 
@@ -63,21 +71,26 @@ Determine if the text has words or phrases that:
 * Hint at a meaning that is not directly stated, or
 * Can have more than one meaning, such as working on a literal and figurative level at the same time. Example in English: “The chef cuts corners when slicing the fish.” Non-literal: The chef is preparing the fish in an easy or cheap way. Literal: The chef is cutting the fish into shapes that don’t have sharp corners.  
 
-When checking for non-literal text, also consider how sentences are combined together, such as if a word in one sentence is critical to accurately understanding the meaning of a later sentence. 
+When checking for ambiguous text, also consider how sentences are combined together, such as if a word in one sentence is critical to accurately understanding the meaning of a later sentence. 
 
-If the text has implied meaning, explain it or provide a literal alternative using one of the techniques in the [Methods](.methods/) section.
+If the text has implied meaning, explain it or provide an unambiguous alternative using one of the techniques in the [Methods](.methods/) section.
 
 </div>
 
 ## Definitions
 
+- **Abbreviation**: TBD (a shortened form of a word or a phrase).
+- **Acronym**: TBD (a type of abbreviation formed from the initial letters of other words, often pronounced as a word).
+- **Ambiguous number**: TBD (such as when date formatting can have different meanings in different cultures).
+- **Ambiguously pronounced text**: TBD (including words that leave out letters or diacritics needed to read the words phonetically, such as in Arabic and Hebrew.)
 - **Back translation** is a two-step process of translating text into another language and then back to its original language. Also called reverse translation, this process can help identify phrases that may lose their intended meaning when translated. 
-- **Content publisher** The creative individual or organization responsible for curating, producing, and distributing various forms of content to engage and inform audiences. Includes tools used by the publisher such as HTML and JSON and content management systems like Wix and WordPress. 
+- **Diacritic**: TBD, (a sign, such as an accent or other type of glyph, when added above or below a letter indicates a difference in pronunciation from the same letter when unmarked or marked differently) such as in Arabic and Hebrew.
 - **Emoji character** An emoji character is a small digital image with Unicode for its literal meaning, such as 🌴(“Palm tree”). But emojis often have implied meaning that users may need help understanding. Common examples of emojis used in non-literal ways:
   -  💯(“Hundred points”) can be used in various ways, such as to indicate a perfect score or complete agreement. 
   - 🙃 (“Upside-down face”) is often used to indicate sarcasm or silliness.
 - **Literal text** uses the direct meaning of words to convey exactly what is written. Unlike non-literal or figurative language, literal text does not have implied meaning. 
 - **Non-literal text** uses words or phrases in a way that goes beyond their standard or dictionary meaning to express deeper, more complex ideas. 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, and similes. More detailed examples are available in the [Methods](.methods/) section.
+- **Publisher** The individual or organization responsible for curating, producing, and distributing various forms of content to engage and inform audiences. Includes tools used by the publisher such as HTML and JSON and content management systems like Wix and WordPress. 
 - **User agent** W3C defines user agent as any software that retrieves, renders, and facilitates end-user interaction with Web content, or whose user interface is implemented using Web technologies. 
-Examples: Web browsers, media players, operating system shells, plug-ins, consumer electronics with Web-widgets, and stand-alone applications or embedded applications that help in retrieving, rendering, and interacting with Web content. 
+    - Examples: Web browsers, media players, operating system shells, plug-ins, consumer electronics with Web-widgets, and stand-alone applications or embedded applications that help in retrieving, rendering, and interacting with Web content. 

how-to/outcomes/clear-meaning/methods.md

@@ -11,7 +11,7 @@ layout: layout/methods.md
 
 </div>
 
-## Supplimental
+## Supplemental
 
 <div class="nested">
 

how-to/outcomes/clear-meaning/methods/explain-ambiguous-text/explain-ambiguous-text.json

@@ -3,6 +3,6 @@
     "index": 1,
     "title": "Explain ambiguous text or provide an unambiguous alternative",
     "slug": "explain-ambiguous-text",
-    "description": "@@@"
+    "description": ""
   }
 }

how-to/outcomes/clear-meaning/methods/explain-ambiguous-text/index.md

@@ -5,23 +5,27 @@ subtitle: Introduction
 
 <dl class="method-card">
   <div>
-    <dt>Level: Foundational</dt>
-    <dd>@@@</dd>
+    <dt>Level:</dt>
+    <dd>Foundational</dd>
   </div>
 </dl>
 
 Determine if the text has:
-- non-literal text, 
-- abbreviations and acronyms, 
-- ambiguous numbers, or 
-- text missing letters or diacritics
+- Non-literal text, such as idioms, metaphors, similes, and sarcasm.
+- Abbreviations or acronyms that are not explained on first use.
+- Ambiguous numbers such as date formatting that can have different meanings in different cultures.
+- Text  that leaves out letters or diacritics needed to read the words phonetically, such as in Arabic or Hebrew.
 
 If the text is ambiguous, explain it or provide an alternative using one of the techniques in the techniques section.
 
 
 
 ## Techniques
 
-* **Author technique (General):** Spell out the meaning in brackens after the first use.
-* **Author technique (General):** Linking to a glossary.
-* **Author technique (HTML):** Include text that explains the meaning using an abbriviation.
+* **Author technique (General)**: Explain the meaning in brackets after the first use.
+* **Author technique (General)**: Explain the meaning in a consecutive block of text.
+* **Author technique (General)**: Include a link to a glossary, pop-up, or tooltip.
+* **Author technique (General)**: Use translation tools to help identify ambiguous text during back translation.
+* **Author technique (HTML)**: Include text that explains the meaning using an  abbreviation `<abbr>` element.
+
+<p class="ednote">This guideline will include definitions and examples in English of common types of non-literal text. This guideline will also link to examples of non-literal text in a wide variety of languages, including Arabic, Chinese (Mandarin), Hindi, Japanese, and Russian.</p>

how-to/outcomes/focus-appearance/index.md

@@ -20,20 +20,20 @@ The keyboard focus must have a sufficient visual indicator.
 
 For each focusable item:
 
-1. Is the user-agent default focus indicator used? (Prerequisite)
+1. Is the user-agent default focus indicator used?
     1. Yes, the [user-agent default indicator](methods/default-focus-indicator) is used AND the *accessibility support set* meets [Custom focus indicators](methods/custom-focus-indicator). Stop.
     2. No, continue.
 
 
-3. Is the focus indicator defined by the author? (Baseline)
+2. Is the focus indicator defined by the author?
     1.  Yes, indicator must meet [Custom focus indicators](methods/custom-focus-indicator). Stop.
     2.  No, fail.
 
   </div>
 
-### Supplimental Requirements
+### Supplemental Requirements
 
-- [Supplimentary indicators](methods/supplimentary-indicators).
+- [Supplementary indicators](methods/supplementary-indicators).
 
 
 ### Assertions

how-to/outcomes/focus-appearance/methods.md

@@ -14,6 +14,10 @@ layout: layout/methods.md
 
 </div>
 
-## Supplimental
+## Supplemental Requirements
 
-- [Supplimentary indicators](methods/supplimentary-indicators)
+<div class="nested">
+
+- [Supplementary indicators](methods/supplementary-indicators)
+
+</div>

how-to/outcomes/focus-appearance/methods/default-focus-indicator/default-focus-indicator.json

@@ -1,8 +1,8 @@
 {
   "method": {
     "index": 1,
-    "title": "Using the default focus indicator",
-    "slug": "default-focus-indicator",
-    "description": "The platform's default indicator is used."
+    "title": "r",
+    "slug": "User-agent default indicator",
+    "description": "Focusable item uses the user agent default indicator."
   }
 }

how-to/outcomes/text-alternatives/index.md → how-to/outcomes/image-alternatives/index.md

@@ -19,23 +19,23 @@ If there is no information conveyed by the image, the user's assistive technolog
 
 ### Foundational Requirements
 
-1. Would removing the image impact how people understand the page? (Prerequisite)
-   1. No, [decorative images are programmatically hidden](methods/decorative-images). Stop.
+1. Would removing the image impact how people understand the page?
+   1. No, [decorative image is programmatically hidden](methods/decorative-images). Stop.
    2. Yes, continue.
 
-2. Is the image presented in a way that is available to user agents and assistive technology? (Prerequisite)
-   1. Yes, image must meet _Image is programmatically determinable_ AND the _accessibility support set_ incorporates [Equivalent text alternatives are available for images that convey content](methods/equivalent-alternative-text). Stop.
+2. Is the image presented in a way that is available to user agents and assistive technology?
+   1. Yes, image must meet _Image is programmatically determinable_ AND the _accessibility support set_ incorporates [Equivalent text alternative is available for image that conveys content](methods/equivalent-alternative-text). Stop.
    2. No, continue.
 
-3. Is an equivalent text alternative available for the image? (Baseline)
-   1. Yes, image must meet [Equivalent text alternatives are available for images that convey content](methods/equivalent-alternative-text). Stop.
+3. Is an equivalent text alternative available for the image?
+   1. Yes, image must meet [Equivalent text alternative is available for image that conves content](methods/equivalent-alternative-text). Stop.
    2. No, fail.
 
 </div>
 
-### Supplimental Requirements
+### Supplemental Requirements
 
-- [The role and importance of images are programmatically indicated](methods/role-of-images) (Supporting requirement).
+- [The role and importance of the image is programmatically indicated](methods/role-of-images) (Supporting requirement).
 - [The type of image (photo, icon, etc.) is indicated](methods/type-of-image)  (Supporting requirement).
 - [Auto generated text descriptions are editable by content creator](methods/editable-alt-text)  (Supporting requirement).
 

how-to/outcomes/image-alternatives/methods.md

@@ -0,0 +1,22 @@
+---
+layout: layout/methods.md
+---
+
+## Foundational Requirements
+
+<div class="nested">
+
+- [Decorative image is programmatically hidden](methods/decorative-images)
+- [Equivalent text alternative is available for image that conveys content](methods/equivalent-alternative-text)
+
+</div>
+
+## Supplemental Requirements
+
+<div class="nested">
+
+- [The role and importance of the image is programmatically indicated](methods/role-of-images) (Supporting requirement).
+- [The type of image (photo, icon, etc.) is indicated](methods/type-of-image)  (Supporting requirement).
+- [Auto generated text descriptions are editable by content creator](methods/editable-alt-text)  (Supporting requirement).
+
+</div>

how-to/outcomes/image-alternatives/outcome.json

@@ -0,0 +1,5 @@
+{
+  "index": 0,
+  "title": "Image Alternatives",
+  "description": "Users have equivalent alternatives for images."
+}