Summary

Note: current activity can be tracked in the wa1-coga-design-guide github repo.

Scope

Introduce tooling and process to support the Cognitive and Learning Disabilities Accessibility Task Force in publishing the Design Guide section of Content Usable TR note as part of the new Supporting Documents for WCAG 2 section of the WAI site. The new pages and the TR note need to share content but will have different presentation styles (document vs. web page).

Audience

Primary: People who want the web products they work on to provide excellent cognitive accessibility (including designers, developers, content creators, quality assurance testers). Could be accessibility champions, could be team members looking for "what to do" guidance.
Secondary: Researchers and Educators

Use cases

A designer or developer who is building a new feature, wants to learn ways to provide best cognitive accessibility practice
A Quality Assurance engineer who needs to approve the implementation of a new feature and wants to find a definitive source and intent
A content strategist wants to assess whether the content in a new feature has accessibility implications
An accessibility auditor wants to verify if something was built conform the standard

See also the more comprehensive current user flows.

Introduction

The Cognitive and Learning Disabilities Accessibility Task Force publication Content Usable contains practical guidance developed from the research and gap analysis activities. It has three main sections: User Stories, Personas and a Design Guide. The Design Guide contains some 50 Patterns for Content Creators, Designers and Developers to implement in order to improve cognitive accessibility. However, the document format of a W3C TR note is not ideal for reviewing a large number of such Patterns and stakeholders have requested an interactive web resource for improved access. A proof of concept was previously created.

At the same time, there is a current WAI project to redesign the Supporting Documents for WCAG 2. This aims to make these documents easier to discover, navigate, and apply to web projects. The Supporting Documents are the "non-normative" technical guidance from the AG Working Group, such as Techniques and Understanding.

This page presents the requirements so the Design Guide can appear as part of these new resources.

Overview

The following aspects need to be addressed:

Integration with the WAI Supporting Documents project
Format of content required for the new supporting documents
Structure within a page
Organisation across web pages
Navigation within the Design Guide
Navigation and linkage within the supporting docs and WAI site
Integration with search
Pipeline to create both new and existing note
Enhanced TF editorial workflow
Updates to current content

Integration with the WAI Supporting Documents project

This project is being led by Hidde. The exact formats are being determined by the Supporting Documents project, perhaps with minor adjustments if required for this work.

Current discussion has agreed the following:

Build pipeline

Supporting Docs will have own GitHub Repo
- new wai-coga-design-guide repo for content
Integrated into exist WIA website
- ? URIs ?
Existing WAI website Jeckyll-based SSG
- liquid templates
- short codes for components
- theme
GitHub action to push from Coga
- may need content process depending on exact TF editing process
trigger
- manual like WAI site publish GitHub action
- ?or on push to main on coga repo

Content Format and Layout technologies

Markdown with yaml front matter
- Pattern text in content, side bar links in yaml
minimal HTML, if any, ideally using custom tags
liquid templates if required
Page layouts (with header footer etc) provide by Supporting Documents project

Structure and Navigation of new repo and WAI resource

As scoped by the Supporting Documents project.

In wai-coga-design-guide repo

/ _objectives -> *.md
/ _patterns -> *.md
/ content -> about.md, all.md

linked to from Supporting Docs 'index' page in Wai site:
pages
- "About Design Guide" page - summary / introduction
- "Design Guide" page like all techniques page - index / navigation for browsing
  - collapsible Objectives
- page per Objective - as per current TF format
- page per Pattern - mockup but using the new DG template
outgoing links from pages in side bar
- Design Guide internal links
- external links eg to related techniques
The "Help Improve This page" section MUST link to coga repo not wai-coga-design-guide

Search

Integration with WAI Search as defined by the Supporting Documents project.

Changes to coga repo and workflow

There should be a single review and approval cycle for each Objective / Pattern. The "approved" Patterns will be immediately published as part of the "Supporting Documents". They also get merged into the main branch of the "Note" ready for it's next publication.

Design guide document to be broken up:
- page per Objective and per Pattern
- minimal pure HTML content so can be used by
  - respec including document for the TR note
  - action that copies to WAI repo

New Coga editing tooling for New Pages and Existing Note

See detailed investigation in Tooling

input format, either:
- Preferred, new shared format, per pattern - preferred, also supports new workflow (below), or
- Existing note HTML + respc (or multi-page version) - complex to edit and automate
outputs
- Design Guide as Supporting docs - as defined above
- TR note - HTML + respec
  - Design Guide + other sections
  - integrates with W3C note publishing process
Repositories - coga, Wai new?
Tooling - GitHub actions
Triggers / flow
- manual or on merge to master when updates approvded by TF, or
- pull from the Supporting Docs or Note to be updated

Enhanced TF Editorial Workflow

The TF do not like working directly with HTML source. Ideally could work in a google docs like environment with track changes and commenting. A work able solution may be as per htmldiffs with or without in screen comments. This topic is explored in detail in the Tooling page.

Enable Taskforce to edit plain content without markup:
- Live edit
- Track changes + other formatting
- Commments
Semi-automated editorial step to ensure correct structure and markup
- Currently manual: HTML + respec in GitHub -> extract text to Google Doc -> edit -> reformat in HTML + respec
Frontend to the pipeline (above)

Possible implementation technologies

Netlify CMS - simple editor with YAML + markdown in GitHub content storage
Sanity - Google doc like editing tools with own data format + data server
Craft CMS being used in W3C site redesign

Updates to current content

Review all patterns not part of current review batch
Add links to other patterns and other Supporting docs in the side bar