Re: [Editorial] Proposed clarification to checkpoint 12.5 (documentation of changes that affect accessibility)

hey Ian (see MN below)


At 11:21 AM 4/18/01, Ian Jacobs wrote:
>mark novak wrote:
>>
>> hi Ian, Denis and all:
>>
>> >I agree that [checkpoint 12.5] is hard to verify (as many others
>> >are in our document) and impossible to automate.
>>
>> for this an "other reasons", is there a chance that you could enhance
>> the current defintion of "documentation", such that it might even
>> include a bullet list (e.g., like AT does),  and then
>> Guideline 12 could be simplified to perhaps "one" priority
>> one checkpoint?
>
>I don't think that the checkpoints of Guideline 12 can be
>reduced to one checkpoint. The requirements are:
>
> a) What must be documented:
>    - feature that benefit accessibility (12.2)
>    - the default input configuration (12.3)
>    - software releases that affect accessibility (12.5)
>
>    Our definition of "documentation" is not normative.
>    Only the above checkpoints make requirements about
>    what's in the documentation.
>
> b) How the documentation must be organized:
>    - it must have a section just about features
>      that benefit accessibility (12.4).
>
> c) Finally, the documentation must conform to WCAG (12.1).

MN:  sorry, i don't agree.  do whatever you see best, but I still think
the 5 checkpoints of Guideline 12 can be condensed.

for checkpoint 12.1, the definition or "expectation" of documentation, for
example,
if the product allows user input via the keyboard, then the documentation
ought to include the "default key bindings", otherwise the "documentation"
isn't complete.   If the product allows user input via voice commands,
then the documentation ought to include a list of the "default voice commands",
otherwise the "documentation" isn't complete. That is the point I was
trying to make regarding how I view checkpoint 12.3 as part of 12.1.
I can understand the fear, from an "accessibility point of
view",  that we'd want to special case this, but i'd prefer to see it
somehow worded into 12.1 as part of what it means to document
the UA so the user can "use it".

also , if you added the wording "for each software release" into 12.1,
which is really what you want, then checkpoint 12.5 is not needed.

looking at checkpoint 12.5 from a totally backwards point of view, I could
develop a new UA version 1.0, and by performing 12.1, 12.2, and 12.3
comply or....  Then for any later software releases of my UA, all i'd ever have
to change in my documentation is 12.5, anything to do with accessibility,
despite the fact that some other serious changes were made.   See
my point?  There is nothing in 12.1, 12.2, and 12.3 about each release.
I of course assume it is implied, ouch!  Would it not be easier to add that
wording to 12.1, and get rid of 12.5?

next

I do not see enough difference in 12.2 and 12.4 to justify both.  12.4
claims to be a
specific requirement of 12.2, yet after reading F2F mtg minutes, and tech. doc.,
i'm not understanding that to be clear.  is it limited in scope, and if
yes, then that difference is not clear to me.   i don't see it addressing
structure either.  i still feel you could just roll them both into one
checkpoint.

another problem i have with 12.2 and 12.4, is exactly what or exactly who
is going to determine what features benefit accessibilty and thus require
documentation as such.  accessibility added to web documents under w3c
development
may be easy to define, others as part of the UI or UA experience on a
particular platform are much more ambiguous.

as an example:

i noted in the "test run of a user agent, Opera 5.1/Win", under checkpoint
12.4,
Jonny typed "see 12.2".  <smile>

mark

> - Ian
>
>--
>Ian Jacobs (ij@w3.org)   http://www.w3.org/People/Jacobs
>Tel:                     +1 831 457-2842
>Cell:                    +1 917 450-8783

>mark novak wrote:
>>
>> hi Ian, Denis and all:
>>
>> >I agree that [checkpoint 12.5] is hard to verify (as many others
>> >are in our document) and impossible to automate.
>>
>> for this an "other reasons", is there a chance that you could enhance
>> the current defintion of "documentation", such that it might even
>> include a bullet list (e.g., like AT does),  and then
>> Guideline 12 could be simplified to perhaps "one" priority
>> one checkpoint?
>
>I don't think that the checkpoints of Guideline 12 can be
>reduced to one checkpoint. The requirements are:
>
> a) What must be documented:
>    - feature that benefit accessibility (12.2)
>    - the default input configuration (12.3)
>    - software releases that affect accessibility (12.5)
>
>    Our definition of "documentation" is not normative.
>    Only the above checkpoints make requirements about
>    what's in the documentation.
>
> b) How the documentation must be organized:
>    - it must have a section just about features
>      that benefit accessibility (12.4).
>
> c) Finally, the documentation must conform to WCAG (12.1).
>
> - Ian
>
>--
>Ian Jacobs (ij@w3.org)   http://www.w3.org/People/Jacobs
>Tel:                     +1 831 457-2842
>Cell:                    +1 917 450-8783

Received on Monday, 30 April 2001 18:25:43 UTC