Re: Proposal for WCAG 2.1 editing / review process

On 3/15/2017 12:04 PM, Repsher, Stephen J wrote:
>
> On 3/14/2017 1:25 PM, Repsher, Stephen J 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.
>
> Because the files for editing are HTML snippets, not full HTML files, 
> we can't put working links directly within the files, as they depend 
> on script support. Unfortunately the include mechanism doesn't support 
> including full HTML files and stripping the wrapper stuff, so the 
> files have to be minimalist.
>
> */[Steve] Unless the relevant definitions are called out in the 
> individual SC rawgit views somehow, I would not support pointing to 
> those views.  Which terms have glossary definitions and the content of 
> those definitions can make or break an SC.  In other words, I should 
> be able to fully review an SC from its rawgit view.  Can you provide 
> the technical details of the script inclusion procedure so perhaps I 
> or others could offer suggestions or code?  I could have sworn there 
> were other links in the Accidental Activation SC example, but it looks 
> like you’re moving things around and that link no longer works./*
>
These links aren't available in the view of the code snippets because of 
how the include mechanism works, but would be linked from the issue - 
every definition relevant to the SC would be referenced from the issue, 
at the top. In addition, we would provide a link to a built version of 
the guidelines that includes the SC and generates the link to the 
definitions.

The include mechanism uses the Respec data-include:
https://github.com/w3c/respec/wiki/data--include

That depends on a script in the HTML head, which we can't put on each 
one of these include files. It's in the overall guidelines file, which 
is why glossary links work there but not in the individual files.
>
> *//*
>
>
>
> If we adopt this proposal, the issue would certainly have a pointer to 
> the relevant definitions alongside the pointers to the SC draft (in 
> both edit mode and display mode).
>
> */[Steve] Saying edit mode and display mode is throwing me off… Do you 
> mean the SC GitHub issue?  If so, then please refer to my later email 
> arguing that it’s time to stop trying to maintain those threads as a 
> catch all per SC./*
>
By edit mode, I mean the github URI that shows the source of the file 
with some github wrapper, and has an edit button if people want to edit 
online. People can also edit in a local client, but need to be sure 
they're editing the right file in the right branch, which the above 
referenced URI would indicate.

By display mode, I mean the rawgit URI that shows a rendered view of the 
file in the browser, just like a web page, but minimalist because it's 
just a snip of HTML.

The GitHub issues we've been using would *point* to these two types of 
resources, but the whole goal of the proposal is not to use the issue 
itself to maintain the SC text, because of the reasons you cite.

Michael
>
> *//*
>
>
>
> It's also possible to view a full version of the guidelines that 
> includes the SC proposal, in which the links to terms *would* be 
> active. The URI to that full version would be different for each 
> proposal, but would also be referenced from the issue.
>
>     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.
>
> Yes, this is a big goal for this proposal. The commit history may be 
> difficult for some people to consume, but isn't needed for mainline 
> review. I see it as mainly allowing restoration of old versions of the 
> proposal if a particular path isn't working out.
>
> Michael
>
>     Steve
>
>     *From:*Michael Cooper [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
>