Wcag21-understanding-documents
The AGWG need to review and update the new understanding documents for WCAG 2.1
The survey for approval will be used towards the end of the process, in the meantime, please put yourself down for reviewing one or more docs.
See also: Technique tracking
What to review
The basics to cover are:
- Does it include the things it should?
- Does it provide understanding of the SC! (It is especially helpful if you sign up for one you’re less familiar with.)
- Are there errors or phrasing issues (editorial);
- Does it list enough techniques? (Techniques will be the next step, we don’t expect them to exist yet, but we should know what they are.)
Follow the link to add comments in the main github thread, if you review something and it's ok (no changes), please add a short comment to say so!
For editorial questions please refer to the PF editors style guide.
List of understanding docs
Each link goes through to the github issue where the comments can be added. At the top of each page are links to the SC text and the (rendered) HTML document.
| SC Name and Github link | Reviewers | Updated by | Notes/Status |
|---|---|---|---|
| "Identify Common Purpose" | JF | Detlev | Approved by survey 8th May 2018 |
| "Identify Purpose" | JF | JF | Pending update |
| "Reflow" | Jim Allan / Detlev | Detlev | Approved by survey 8th May 2018. |
| "Non-text contrast" | Bo Campbell (Done), Mike Elledge, Mike Gower (Done) | AlastairC | Ready for survey |
| "Text spacing" | Laura Carlson (Done), E.A. Draffan (Done) | Laura Carlson | Minor updates, ready for survey |
| "Content on Hover or Focus" | Mike Gower (Done), SteveRep | Mike Gower | "PR added", would like review from SteveRep but ready for survey. |
| "Timeouts" | John Kirwood, Lisa Seeman (Done) | AndrewK | Ready for survey |
| "Animation from Interactions" | Glenda Sims (Done) | Glenda Sims | "PR 874" reviewed by AlastairC, ready for survey. |
| "Character Key Shortcuts" | David MacD (Done) | David MacD | Updated in working branch, PR to master added, ready for survey |
| "Label in Name" | Marc Johlic / Jon Avila | MarcJ | Approved by survey 8th May 2018 |
| "Target Size" | Jake Abma (Done) | Jake Abma | Review done, "Pull request 873" reviewed by Kathy, merged to working branch, ready for survey. |
| "Pointer Gestures" | Greg Lowney (Done) | Greg Lowney | Ready for survey |
| "Pointer Cancellation" | SteveRep, Mike Gower (done) | NA | Approved by survey 8th May 2018, would still like Steve's input. |
| "Concurrent Input Mechanisms" | Charles Adams, Michael Gower (Done) | MichaelG | Ready for survey |
| "Orientation" | Bruce Bailey (Done) | MichaelG | Ready for survey |
| "Motion Actuation" | Bruce Bailey (Done) | MichaelG | Ready for survey |
| "Status Changes" | Bruce Bailey (Done), David MacD (Done), SteveRep | David MacD | Ready for survey |
| Text resizing | TBC | TBC | Need to add text around the effect of breakpoints on text-sizing. |
Updating understanding documents
There are four levels to updates, from easy to involved:
- Make comments in the github thread. Please try to make it obvious where you would like to see changes.
- Copy the HTML content into a Word or Google doc, and use track changes to show what you'd like to change. Save the document into a comment on github.
- Make small the changes in github (see next section)
- Make a new branch in github to show larger changes (see next section)
Github step-by-step
Step 1: Go to the working branch (this is important!). E.g. To do anything to the 'Non-text contrast' document, select the non-text-contrast branch. From the main github page for WCAG 2.1, select the branch drop-down.
Small, editorial updates
For small updates you can edit the working branch.
Step 2: Navigate to the understanding document, understanding > 21 > understanding-file.html
Step 3: Click the edit button (pen icon, top right). Make your edits, and save it at the bottom by "Commit changes". Give it a little description of the changes made.
Step 4: Add a comment to the github issue for that document (links on this page), saying you've updated it.
Significant updates
For more significant edits (e.g. moving sections around) create a new branch to work in. Do step 1 first, select the working branch.
Step 2a: Select the branch drop down and start typing the name of the branch. E.g. 'non-text-contrast', but add your name at the end. E.g. 'non-text-contrast-alastair', and select 'Create new branch'.
Step 3a: Navigate to the file and edit it. You may wish to copy-paste the whole thing into a text-editor, make changes, then copy back. Save changes by committing them.
Step 4a: Create a pull request (link, top-right). Make sure the first option is the working branch (e.g. 'non-text-contrast') and the second is your new branch. It will also help to reference that pull request in the thread for the Understanding document. E.g. pull request 876 can be referenced by adding a comment that includes #876.