Re: Glossary quality check script

This is an excellent tool.  Thank you Michael.

The fact that they are unwieldy is exactly why we have “terms” as you point
out.

The test that the definitions can drop in for the words is the standard
test for a definition in standards.  So excellent job.

We used the same test in WCAG 2.0 and I am chagrined that anything got
through.

I did find a lot of bad definitions when we used this technique (but we
didn’t have this tool !) in WCAG 2.      (We also occasionally found that,
if the definition was short enough, it was better to just put the
definition into the provision.   This made it less jargon-y and easier to
read for those not used to using our jargon.  Only worked one or two places
though.)

At any rate — this is an excellent tool — and exercise.   The resulting
provision does not need to be easy to read or parse,  but it DOES have to
make sense and be accurate.   Or else the definition or the SC have a
problem.

I sometimes found early SC that were circular this way too.  Where we
talked in circles but didn’t actually explain what we meant.

Thanks Michael

G



Sent from my iPad

On Sep 29, 2017, at 6:12 PM, Michael Cooper <cooper@w3.org> wrote:

One thing the QA checklist
<https://www.w3.org/WAI/GL/wiki/WCAG_2.1_QA_Checklist> mentions is that the
definitions of terms in WCAG 2 should be able to be replaced directly into
the SC and things still make sense. To test this, I added a script that
will substitute definitions in place of terms, if the "defs" parameter is
present in the URI, i.e.,

https://rawgit.com/w3c/wcag21/master/guidelines/index.html?defs

The script only substitutes the first line of the definition, since that is
the part that's meant to be drop-in replaceable. It puts the original term
that was linked into the title attribute of the replaced link, to help
figure out what was originally there (I could also make that more directly
visible if people want). The script may only work with newer browsers, and
only if the base script has run - there should be a "Respec" button in the
top right fairly early in the navigation order, and the page may need to be
refreshed if that hasn't shown up.

A few observations / comments:

   - Some SC become very unwieldy when expanded this way, though that's why
   we moved a lot of content to terms;
   - There are WCAG 2.0 terms that don't work out well this way, but I
   don't think we will fix that, this is mainly to look at WCAG 2.1 quality;
   - The group may decide it wants to be less particular than me about
   exact drop-in ability of definitions, but I still think it's a useful
   exercise and a rough goal we should maintain for consistency and
   understandability;
   - Some SC may become fairly nonsensical and that should be a cue that
   our definition isn't working well and needs improvement.

I'll leave it at that for now, people can look over the guidelines with
this filter as it suits them and raise any flags you see. I expect
eventually to file issues on terms I think really aren't working out seen
in this context.

Michael