Reimplement associated techniques as data

[kfranqueiro]

This replaces the HTML for each Understanding page's Techniques section with a data representation of the same information, to improve consistency, reduce likelihood of mistakes, and eventually enable restoring the structured techniques field to success criteria in the JSON export (see the first list item in #4393).

All associated techniques are now defined in understanding/understanding.11tydata.js under the associatedTechniques field, in a way that should make the simplest cases easier to define than they were before. Documentation is added in this PR. In addition, various common mistakes are checked for at runtime with specific error messages, and typings are also defined, enabling some amount of autocomplete and feedback in editors that support TypeScript, such as Visual Studio Code.

Most of the changes in this PR involve the build system and centralized templates; the only changes to the Understanding pages themselves are to use the new template rather than spell out the related techniques within HTML.

However, this does visibly impact some pages within the informative docs. I have outlined notable changes to focus TF/WG review on below.

Changes to Understanding pages

This list describes changes to the Techniques section within respective SC pages.

• Swaps out "technology-specific techniques below" phrasing seen in the following 2 pages, to standardize on the more common "the following techniques", since technology specificity is already indicated by the technique ID:
  • 1.2.2: Captions (Prerecorded) (compare to current 1.2.2)
  • 4.1.2: Name, Role, Value (compare to current 4.1.2)
• Appends "techniques" in cases of "using one of the following"
  • 1.2.3: Audio Description or Media Alternative (Prerecorded) (compare to current 1.2.3)
  • 1.2.5: Audio Description (Prerecorded) (compare to current 1.2.5)
  • 1.2.7: Extended Audio Description (Prerecorded) (compare to current 1.2.7)
  • 3.3.2: Labels or Instructions (compare to current 3.3.2)
  • 4.1.3: Status Messages (compare to current 4.1.3)
• In 1.2.2: Captions (Prerecorded) (compare to current 1.2.2) and 1.2.4: Captions (Live) (compare to current 1.2.4), moves "using any readily available …" into the list in the subsequent item which references the same parent technique(s), to avoid arbitrary suffixes and the special case of a suffix after an "AND" relationship in 1.2.4
• In 1.4.8: Visual Presentation (compare to current 1.4.8), removes trailing "OR"s, which seemed redundant of the preceding text
• In 2.1.3: Keyboard (No Exception) (compare to current 2.1.3), converts the paragraph under Sufficient into a list item for consistent representation both visually and in data (this matches how Quickref used to convert it)
• In 2.2.6: Timeouts (compare to current 2.2.6), rephrases items to use consistent verb tense
• In 2.5.5: Target Size (Enhanced) (compare to current 2.5.5), removes "Select the situation below" paragraph which doesn’t make sense in this context (this SC does not define situations for sufficient techniques)
• In 3.3.3: Error Suggestion (compare to current 3.3.3), moves note to bottom of Sufficient for consistency with other SC pages, to avoid a special case

Changes to Techniques pages

This list describes changes within the About this Technique box, which represents the same relationships as the SC pages, but in reverse.

• Fixes incorrectly-capitalized initial letter at beginning of phrase:
  • ARIA7 (compare to current ARIA7)
  • ARIA8 (compare to current ARIA8)
  • G105 (compare to current G105)
  • G181 (compare to current G181)
  • H77 (compare to current H77)
  • H78 (compare to current H78)
  • H79 (compare to current H79)
  • H81 (compare to current H81)
• Removes "using one of the following techniques:", as it shouldn’t have appeared in this context:
  • C7 (compare to current C7)
  • H33 (compare to current H33) (resolves H33: Broken About this Technique #4503)
• Adds "using a more specific technique", previously missed due to 1.1.1’s unique group structuring:
  • G68 (compare to current G68)
  • G82 (compare to current G82)
  • G94 (compare to current G94)
  • G95 (compare to current G95)
  • G100 (compare to current G100)
• C28 (compare to current C28) is corrected to say "when combined with other techniques", which is consistent with other instances involving a plurality of "using" relationships; this was missed before because "using one or more" was incorrectly treated as "using one"
• G87 (compare to current G87)'s references to 1.2.2 are de-duplicated, because both technically involve use of a more specific technique; the first was not detected as such before

[netlify]

✅ Deploy Preview for wcag2 ready!

Name	Link
🔨 Latest commit	c8c2763
🔍 Latest deploy log	https://app.netlify.com/projects/wcag2/deploys/689a0413e14f600008879d9e
😎 Deploy Preview	https://deploy-preview-4509--wcag2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[mbgower]

TF members are asked to review the differences in wording within list items, etc., that will result from this (Covered by Changes in... headings in prior comment).
Link provided to documentation, close to top of description, if needed.

[kfranqueiro]

@dbjorge expressed concern at the one-data-file approach, from the standpoint of potential confusion among authors/editors/reviewers, and advocated for storing the data as frontmatter in each existing HTML file. @alastc had also initially asked if keeping the associations within each HTML file would be possible. While it is possible, the ergonomics around editing would be significantly worse.

Here's a breakdown of the 3 possibilities:

Option 1 (current): All in one JS file

• Pro: First-class JS/TS editing experience:
  • Has access to TypeScript typings, which provides Intellisense/etc. in editors that support it (e.g. Visual Studio Code)
  • Can be auto-formatted with Prettier the same way as the TypeScript files in the repository
• Pro: Because it is accessible to tsc, it can be typechecked at build time, to prevent mistakes
• Con: Separates the associations completely from the original files, potentially making it harder to find
  • Mitigation: there is a comment above the include in every HTML file, and both the shortname and SC number is included for each SC in the single data file
• Con: Since the content is separate, future changes to associations will not be reflected within the git history of a particular SC's HTML file; moreover, since associations for all SCs are in one file, it may not be clear which SC's associations were changed at a glance from commit history (the Blame view could still be used for this)

Option 2: Frontmatter in each HTML file

(I investigated this option very briefly; the cons listed below immediately discouraged me from an authoring perspective, which was a big factor considering I authored the entire 1400-line data file by hand, and there was no way I was doing that without allowing my IDE to help.)

• Pro: Is in the same file as the rest of the SC's content
• Con: Lack of robust support for Eleventy's JS frontmatter in code editors or tooling to assist with editing or formatting
• Con: No build-time type checking, which may make some mistakes harder to spot

Option 3: shortname.11tydata.js accompanying each HTML file

(Note I haven't tested this option yet; it should require minimal template changes.)

• Pro: Should have the same pros as Option 1
• Con: Will further hamper IDEs' quick-open feature (i.e., the existing problem of accidentally opening guidelines/.../shortname.html instead of understanding/.../shortname.html is now compounded by a 3rd option, understanding/.../shortname.11tydata.js)
• Con: Will make each understanding/2x/ directory twice as crowded
• Con: Has the same con as Option 1 related to git history, with the partial improvement that history of associations for an individual SC would still be easy to view

I chose option 1 because IMO it has the fewest ergonomics issues for people who frequently edit files in the repo. However, I can see where it might be extremely daunting for would-be contributors who want to fix something, especially if they're not comfortable doing a full checkout (editing a 1400-line file in GitHub is probably not a great experience). So maybe Option 3 is worth testing?

[bruce-usab]

…However, I can see where it might be extremely daunting for would-be contributors who want to fix something

I am all for making things easier for casual would-be contributors.

...especially if they're not comfortable doing a full checkout

I agree that not being able to work on singleton files is a barrier for would-be contributors.

...editing a 1400-line file in GitHub is probably not a great experience

Unfortunately, that's my lived experience with WCAG2ICT and a few other repos. It's not great, but it's not been terrible enough to motivate me to fork a local build.

So maybe Option 3 is worth testing?

I don't think so. I am interested in learning more about the WCAG3 workflow, but maybe after that gets more shaken out.

[iadawn]

Discussed in 1-1 and I am content with this approach given the options.

[mbgower]

My review:
On a high level, it seems a little unusual that we say in the techniques preamble that we say "there may be other ways of meeting" and then use language that seems to require one of the listed techniques. Is it worth tweaking the phrases you are changing to make this more malleable? For instance "using one or more techniques, such as:"

1.2.2: I'm fine with this, but wanted to emphasize that this is not the same as what you did in 4.1.2. First one uses "one or more" and the other "any". I think I understand the rationale; just pointing out the phrase swap is not consistent. As well, here you have merged two separate listings of G87 (which I think is fine). It's a little unusual having a technique bullet with no technique -- but we do it elsewhere; maybe we can eventually get a technique written? I do think we should consider a tweak to the language, changing "that has" to 'with". The rationale is that in most circumstances, it is the author who supplies the video player:

Using any readily available media format with a video player that supports closed captioning

4.1.2: I support modify the phrase "using technology-specific techniques below" with "using one or more of the following techniques"

1.2.3: I think this should also be "one or more", just like you did with 4.1.2. For instance, one could both add narration in the soundtrack and add audio descriptions.
I do think we should strip out the "Using any player that supports audio and video. That seems like a nonsensical bullet, given the circumstances. The new G226 technique makes what I think is inferred here much more explicit.

1.2.5 & 1.2.7: Your change is fine. I think we should also strip out the unlinked generic bullet for same reasons as 1.2.3

3.3.2 & 4.1.3: Your change is fine.

1.2.4: I already commented on this in 1.2.2. I think the same tweak to wording is appropriate here.

1.4.8: This is a little unusual. I agree with taking out the "OR" but I wonder if we should tweak the Instructions to read:

...you must satisfy each of the numbered requirements, using one or more of the listed techniques."

2.1.3: Fine.

2.2.6: It looks like all that's changed is removing the terminal punctuation. Although we do normally have no period at the ends of the bulleted technique items, it's a little odd in this situation, because there is no preamble, and no link. I can live with it.

2.5.5: Fine (and removing periods okay too, for consistency).

3.3.3: Fine.

[kfranqueiro]

Responding to @mbgower; I am suggesting separating a few comments into their own issue/PR when they go beyond migrating the existing content and might prompt further discussion. I'd rather avoid needing to track multiple big threads within this already-big PR, and don't want to bury editorial changes in this PR that would clearly go beyond migrating what currently exists.

On a high level, it seems a little unusual that we say in the techniques preamble that "there may be other ways of meeting" and then use language that seems to require one of the listed techniques. Is it worth tweaking the phrases you are changing to make this more malleable? For instance "using one or more techniques, such as:"

I'm a bit reluctant to make the common "using" phrase even wordier unless we really think it's warranted (given it's existed as-is for years), and I'd want to run this by the rest of the TF. It might spawn enough discussion to warrant a separate issue/PR.

1.2.2: I'm fine with this, but wanted to emphasize that this is not the same as what you did in 4.1.2. First one uses "one or more" and the other "any". I think I understand the rationale; just pointing out the phrase swap is not consistent.

1.2.2's original wording explicitly included "any"; 4.1.2's did not, but would have defaulted to just "one", and the intended plurality was unclear to me. I could certainly switch 4.1.2 to "any" as well if we think it works better there.

(1.2.2) I do think we should consider a tweak to the language, changing "that has" to 'with". The rationale is that in most circumstances, it is the author who supplies the video player:

Using any readily available media format with a video player that supports closed captioning

1.2.4: I already commented on this in 1.2.2. I think the same tweak to wording is appropriate here.

Interesting point; this goes beyond porting the existing phrasing, and I think this could potentially spawn enough discussion to warrant its own separate PR.

1.2.3: I think this should also be "one or more", just like you did with 4.1.2. For instance, one could both add narration in the soundtrack and add audio descriptions. I do think we should strip out the "Using any player that supports audio and video. That seems like a nonsensical bullet, given the circumstances. The new G226 technique makes what I think is inferred here much more explicit.

1.2.5 & 1.2.7: Your change is fine. I think we should also strip out the unlinked generic bullet for same reasons as 1.2.3

This is asking for changes beyond porting what existed. The wording for 1.2.3 remains completely intact in this PR (including the wording of exactly "one"). I think this would warrant a separate PR.

1.4.8: This is a little unusual. I agree with taking out the "OR" but I wonder if we should tweak the Instructions to read:

...you must satisfy each of the numbered requirements, using one or more of the listed techniques."

You are changing "one" to "one or more" in the process, which contradicts the original text (and the "OR"s we are removing). You're also shifting "numbered" from referring to the items (which I have to assume alluded to the technique IDs, unless this was actually an ol at some point in the past) to the requirements (which are sort of numbered, but using spelled-out ordinals rather than actual numerals, so this might seem slightly awkward).

How about: "you must satisfy each requirement using one of its listed techniques"?

2.2.6: It looks like all that's changed is removing the terminal punctuation. Although we do normally have no period at the ends of the bulleted technique items, it's a little odd in this situation, because there is no preamble, and no link. I can live with it.

The verb conjugation at the beginning of each item also changed.

[bruce-usab]

Briefly discuss on backlog call, many concerns can/will be addressed as new Issues/PR created by @kfranqueiro after this is merged.