W3C home > Mailing lists > Public > w3c-wai-gl@w3.org > January to March 2017

Proposal for WCAG 2.1 editing / review process

From: Michael Cooper <cooper@w3.org>
Date: Mon, 13 Mar 2017 14:20:16 -0400
To: AG WG <w3c-wai-gl@w3.org>
Message-ID: <e2c3e322-f85e-62c5-4725-81ae59e8eab3@w3.org>
I've been working with Andrew on ways to make the WCAG 2.1 source easier 
to manage proposals for SC. This still uses GitHub features, but should 
simplify some aspects of it and make it more possible for people to 
share the effort. I've set up a demonstration of what the files would 
look like at:

https://github.com/w3c/wcag21/tree/structure_proposal/guidelines

You see new subdirectories for "sc" and "terms" which contain files for 
each proposal - one file for each success criterion or term. The 2.1 
stuff is in a "21" subdirectory to make it easier to find them among the 
2.0 stuff, which is in a 20 subdirectory. These files are included into 
the main guidelines document via a script include feature.

To work on a success criterion, you would edit the file for the 
particular SC (and any terms if needed) - which is just a snippit of 
HTML. To help separate all the various pieces of work, you would also 
edit in a branch that just has the edits for that one SC. In the issue 
proposal for the SC, it would point (at the top of the issue) to the 
right place, so people know for sure where the latest version is both 
for review and for editing. We would give everyone in the WG access to 
edit these files, so we don't have the problem we've been having with 
people being unable to update the proposal with the latest version.

To show what these files look like, the first one alphabetically is:

https://github.com/w3c/wcag21/blob/structure_proposal/guidelines/sc/21/accidental-activation.html

This is the file where edits to the proposals would be made. To see what 
the proposal looks like without raw HTML and the GitHub cruft, you can 
access the rawgit version of that same file:

https://rawgit.com/w3c/wcag21/structure_proposal/guidelines/sc/21/accidental-activation.html

We would make sure links to those are easy to find, and point to them 
from issues and surveys. SC managers would be able to update the 
proposal as needed, so we could designate these as the "current version" 
and avoid the questions we have now about where the latest version 
actually sits. Anybody in the WG would be able to pitch in and help out 
if needed. Once the content in these files was approved by the WG, we 
would simply merge them into the editors' draft (the editors would 
manage the process of making the include happen in the right place).

This proposal still uses GitHub, which I know is challenging, but I 
think is nonetheless a lot easier:

  * People can see rendered versions of proposed SC edits rather than
    having to read HTML source;
  * We can reference the files as the official "latest version" so
    people don't have to look around through issue comments to find it;
  * We can use the git history to easily look at older versions of the
    proposal if needed;
  * People can edit either online or locally;
  * We don't have to deal with pull requests (and fragmentation of
    comments);
  * It's easier to find the right thing to edit rather than working with
    the whole guidelines file as people had to do in the previous round;
  * The permissions would be set so other people in the WG can help out
    if people have tool difficulty.

I wanted to give people an opportunity to look at this and see if it 
would help our process. It's not perfect, there are still complexities, 
but I think this structure allows us to support people around the 
complexities better. If we decide to go ahead with this structure, I'll 
set things up further so all the working branches exist and the issues 
are set up to point to the right place, so people can just continue work 
using this structure.

Michael
Received on Monday, 13 March 2017 18:20:23 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 16 January 2018 15:34:42 UTC