Preview of Techniques / Preview of Understanding documents

Overview of updates

Summary

With the new design, we now:

• clearly mark these documents as part of W3C (logo), part of WAI (colors, layout, fonts), part of WCAG (WCAG is the first word on the page)
• show clearly which set of documents the user is looking at, including which version of WCAG they belong to (2.1, 2.2 etc)
• have clear pointers to other supporting documents and the general “All WCAG Guidance”
• use a lay-out that is also used by other supporting docs (soon: ACT Rules, COGA Design Guide)
• visually distinguish between name of the document (eg “Using aria-label for link purpose”), how it fits in the larger set (“Sufficient to meet 2.4.4”), the actual document content, meta information (eg links to other sources, summary of key terms, definition of the document type)
• invite people to contribute (“Help improve this page”)
• make code examples easier to use (with syntax highlighting
• have both ‘created’ and ‘last updated’ dates on each document

(see Requirements Analysis)

For AGWG approval

Techniques

• Removes “Important Information about Techniques” paragraph at top of each Technique (and add other ways to indicate guidance is non-normative, including “Techniques are not required to meet WCAG” sentence, as discussed in Make “normative” explicit wai-minimal-header-design#41)

For AGWG consideration

Techniques

• In the applicability section, we replace some common technologies with their abbreviations (eg “HTML” instead of “HyperText Markup Language”), to be closer to how people commonly refer to these technologies. They are wrapped in an abbr tag as well as a link to their specification, so confusion should be minimal for those not familiar with the abbreviation.
• Applicabiliity (eg technologies the Technique applies to) is now its own section
• The relationship of a Technique with an SC is displayed in a box underneath the name of the Technique, in the form of a sentence, with type emphasised (Advisory for, Failure of, etc). There are many variations, some examples:
  • when used with: “This technique is Sufficient to meet 1.2: Time-based Media when used with G87: Providing closed captions. ”
  • advisor for: “This technique is Advisory for 3.1: Readable.“
  • sufficient for two: “This technique is: Sufficient to meet 1.1: Text Alternatives and Sufficient to meet 2.4: Navigable “

Understanding

• The “key terms” now just has terms that link to WCAG, not the full definition
• On the “All Understanding documents” page documents are now split out between “Other Understanding documents”
• Previous/Next GL, Previous Success Criterion are now Previous/Next Guideline, Previous/Next Success Criterion

Other updates

• Adds more of the generated files / build artifacts to .gitignore so that they don't end up in the repository (and don't end up causing merge conflicts)

Open questions

• Technique H43 and others are “sufficient when used with an unwritten Technique”. This is displayed for technical reasons, but may leave users confused. Should we display only “sufficient” (technically not 100% correct)? Or should we mark these as advisory until the unwritten Technique is written?

To do

Techniques and Understanding

• In footer, use correct date for “Last updated”, ideally reflecting when that specific Technique/Understanding was last updated (Note 25 October (Hidde): there is some talk in #74 about maybe removing “Last updated :@@@” from these templates, so that this task could be done after publication): relevant: Comment on WCAG 2.2 Draft: please delay adding of new Success Criteria before the current documentation is improved. #1818 (comment)
• Rethink expand/collapse usage re AGWG/Team comments: either use table of contents instead or add ‘expand/collapse all’ with (probably) remembering the choice in localStorage (Hidde feels that route would also require a way to reset, maybe even a different control?)

Techniques specifically

none open

Understanding pages specifically

• Ensure a maximum of two items in the pager (#navigation) at the bottom of the page, there can be one previous and one next (example of where more than two items are displayed: Understanding ACT Rules, pager)
• Make “Key terms” links to their definitions in the WCAG TR document; both inside the content and in the “About this page” box (Note 25 October (Hidde): in #68, it is being doubted whether we should to this at all)