Re: Proposal for WCAG 2.1 editing / review process

Hi Micheal,

If we have clear and simple step-by-step "how to" documentation
(text/images/videos) of  what we need to do, I tend to be in favor of
giving your proposal a try. Such documentation may be able to help
COGA folks (as well as  GitHub newbies).

Lisa, do you think good, accessible, COGA friendly, documentation could help?

Thank you.

Kindest Regards,
Laura

On 3/15/17, Michael Cooper <cooper@w3.org> wrote:
> On 3/14/2017 3:55 PM, lisa.seeman wrote:
>> It is worth checking if people who are voting yes are aware that many
>> people from COGA will still not be able to participate.
> This is a biasing comment on the review. If people have concerns with
> this proposal, they should express them, rather than ask other people
> who haven't heard the concerns to consider the possibility of someone
> else's concerns in their own review.
>
> The only concern I heard yesterday that wasn't based on incomplete
> understanding of the proposal was that some people would still find it
> hard to edit proposals in GitHub. I did say that the proposal doesn't
> fully solve all issues, but I think it makes things significantly easier
> including on that issue, because people don't have to dive into the full
> set of guidelines to find what to edit, and don't have to manage pull
> requests. But yes, the proposal does still involve editing in GitHub.
>
> The only concrete counter-proposal I heard was to allow SC editing in
> Google docs, which people can do online without special tools and in a
> wysiwyg view. From the perspective of a W3C specification editor, we
> cannot migrate our sources wholesale to Google docs, as they are not a
> code version control system, and we need the features of a version
> control system that is code-friendly. So doing edits in Google docs
> means we would have two versions of the SC, one in the Google docs and
> one in the GitHub. In early stages, that could be fine, the editing
> could all happen in the docs, but once we decide it's ready to migrate
> to the spec, we will have two places the SC exists and people will have
> a hard time knowing which version is the current version. That is one of
> the big problems I was trying to solve with this proposal, so doing
> drafts in Google docs leads us back into some of the problems we were
> having a month ago.
>
> That said, if GitHub is an absolute no-go for people and it's better for
> some SC to be developed elsewhere, then in principle we can do that. SC
> managers will have to take responsibility for keeping track of where the
> current version of the SC is, making sure that's clear to everyone else,
> and making sure the SC don't fork after migration into the
> specification. I would really rather get people ramped up on editing in
> GitHub since I think this proposed mechanism of editing in GitHub can
> work for nearly everyone if they give it a chance - there are several
> ways to be successful and we've removed the most complex aspects. That
> would avoid the forking problem, which I think will be a nightmare if we
> re-open that. But if forking is the tradeoff the WG wants, so be it.
>
> Michael
>>
>> Please see the minutes from today's AG call for more discussion
>>
>> All the best
>>
>> Lisa Seeman
>>
>> LinkedIn <http://il.linkedin.com/in/lisaseeman/>, Twitter
>> <https://twitter.com/SeemanLisa>
>>
>>
>>
>>
>> ---- On Tue, 14 Mar 2017 19:25:57 +0200
>> *Repsher<stephen.j.repsher@boeing.com>* wrote ----
>>
>>     I fully support this new approach.  One request I would have
>>     though is to make glossary links work in the Raw Git, preferably
>>     by scripting them into the same page, but linking to separate Raw
>>     Git versions of each definition would also work.
>>
>>     Another advantage of the separate file approach is that the commit
>>     history for a given SC would be straightforward to see.  We should
>>     provide a link to this in the wiki table.
>>
>>     Steve
>>
>>     *From:*Michael Cooper [mailto:cooper@w3.org <mailto:cooper@w3.org>]
>>     *Sent:* Monday, March 13, 2017 2:20 PM
>>     *To:* AG WG <w3c-wai-gl@w3.org <mailto:w3c-wai-gl@w3.org>>
>>     *Subject:* Proposal for WCAG 2.1 editing / review process
>>
>>     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
>>
>>
>>
>
>


-- 
Laura L. Carlson

Received on Wednesday, 15 March 2017 16:03:57 UTC