Re: Feedback on Survey on Changes to Understanding, Techniques, and Quickref to clarify referencing WCAG issues

 
On Jul 8, 2013, at 9:21 PM, Shawn Henry <shawn@w3.org> wrote:

> Below is some feedback on comments in the Survey on Changes to Understanding, Techniques, and Quickref to clarify referencing WCAG issues
> <https://www.w3.org/2002/09/wbs/35422/20130709_referencing/results>
> 
> On: Understanding Techniques for WCAG Success Criteria <http://www.w3.org/WAI/GL/2013/WD-UNDERSTANDING-WCAG20-20130711/understanding-techniques.html>
> 
> Comment Gregg: "FIRST - This is good but I don't think it should be separate from the general understanding intro. collapse both together otherwise I don't think anyone will find this part. no need to be separate."
> 
> Shawn's perspective: One of the main goals for all editing this was to have a place to point people to with clear information about the Techniques, without them having to wade through a lot of other information. This separate page focusing on techniques would be pointed to from 100s of places, including:
> * The Understanding Introduction <http://www.w3.org/WAI/GL/2013/WD-UNDERSTANDING-WCAG20-20130711/intro#introduction-layers-techs-head>
> * The Techniques Abstract <http://www.w3.org/WAI/GL/2013/WD-WCAG20-TECHS-20130711/Overview.html#abstract>
> * The Techniques Introduction <http://www.w3.org/WAI/GL/2013/WD-WCAG20-TECHS-20130711/intro.html>
> * The How to Meet / Quick Ref Introduction <http://www.w3.org/WAI/WCAG20/quickref/20130711/#introduction>
> * Every technique, e.g., the "Techniques are Informative" section of <http://www.w3.org/WAI/GL/2013/WD-WCAG20-TECHS-20130711/G1.html>
> * Every Understanding sub page, e.g., <http://www.w3.org/WAI/GL/2013/WD-UNDERSTANDING-WCAG20-20130711/text-equiv-all.html#text-equiv-all-techniques-head>
> * The FAQ answers (drafted at <http://www.w3.org/WAI/EO/Drafts/WCAGtechniques#faq-not-require>)
> * W3C & WAI announcements & blog post when the docs are published for review and when updated.
> I think they'll find it. :-)
> 

Good point.   but it is very hard to find (only from the TOC)  so I think most people will miss it.
I found it from the survey -- but when I went to look for it in the actual Understanding WCAG 2.0 doc - couldn’t find it at all.   Then  knowing it had to be there I looked around and found a link in the TOC. and then found it. 

I think we want people to find it who don't know that it is there...  

hence my comment.   



> Comment Gregg: "SECOND  Since this text is about "sufficient" techniques please move this down under suffiecient techniques rather than above in techniques in general It can go at the end of the sufficient techniques section"
> 
> Shawn's perspective: I think it gets more visibility higher up in the "Techniques are Informative" section. (Also, if you move it, that section becomes just one sentence.) Note 2 applies to all of the techniques, not just sufficient, yes? So I think it's best left where it is; however, I don't feel strongly...
> 

I don't see a problem with only one sentence in that heading level.   the others are children so there is lots of content under the header.

When people read this -- their eyes (mine do) jump past the upper text and go to the Sufficient text  - and this is about that so it should go there.  that is where people would look for it - and we want them to find it -- in our advice about sufficient techniques.  

> ---
> 
> Rewritten Sufficient and Advisory Techniques section of Understanding intro
> 
> The link is <http://www.w3.org/WAI/GL/2013/WD-UNDERSTANDING-WCAG20-20130711/intro#introduction-layers-techs-head>
> (I didn't want to edit the survey without OK from Michael.)
> 
> ---
> 
> Rewritten Introduction to Techniques for WCAG 2.0 <http://www.w3.org/WAI/GL/2013/WD-WCAG20-TECHS-20130711/intro.html>
> 
> Comment Gregg: "hmmmm - nice and short but I think UNDERSTANDING TECHNIQUES woud be good to duplicate here on techniques document - why not. it is a good place to find this and it won't make the document measurably longer"
> 
> Shawn's perspective: Generally there are several reason for not duplicating content. For one thing, it's a maintenance issue -- have to remember to update it two places. More importantly, it's potentially confusing and very ANNOYING to readers. If they read it one place, then later start reading it another place, they'll have to waste effort to try to figure out if the text is different and if they need to read it all or not.


Maintenance should not be a problem.    We generate all of our docs out of a single source.    All the information from one doc that appears in another is actually pulled from that other document at time of rebuild.  that is why we always publish all our docs together at the same time.   So that they all agree with each other and all the interlinks work etc.

So no matter how many places something exists - you only edit it in one place.  and all the other places get it from there.   It took awhile for michael to set it up that way -- but we would be toast without it.   (we reuse info all over the place -- for example the list of sufficient techniques in Understanding WCAG 2.0  and in How to Meet)    

RE more than one place -- we do that too.   For example the list I just spoke about.

But I THINK that people expect that text explaining the techniques would be in the techniques doc. 

it might also be in the Understanding WCAG 2.0 doc - but then again the Understanding WCAG 2.0 doc contains information duplicated from every other doc -- and brought together.  

I don't feel strongly about this though -  so I will just defer to the group.    It just seemed to me that If I were looking for informaiton on the techniques doc I would go to the top of it.   and that this doesn’t get in the way of using the techniques doc because most of the time you jump straight to the technique ---(or you are dealing with a 500 page doc anyway....


thanks for doing all this Shawn.

g



> 
> ###
> 
> my 2 cents.
> 
> ~Shawn
>