This Wiki page is edited by participants of the WCAG Working Group. It does not necessarily represent consensus and it may have incorrect information or information that is not supported by other Working Group participants, WAI, or W3C. It may also have some very useful information.

Wcag21-understanding-documents

From WCAG WG
Jump to: navigation, search

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:

  1. Make comments in the github thread. Please try to make it obvious where you would like to see changes.
  2. 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.
  3. Make small the changes in github (see next section)
  4. Make a new branch in github to show larger changes (see next section)

Github step-by-step

Github branch dropdown.png

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.