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

Hi Mark,

I argued earlier on this thread the Guideline 12 has three types
of requirements: what must be documented (12.2, 12.3, and 12.5),
organization of the documentation (12.4), and accessibility of
the documentation (12.1).

You wrote: 

> MN:  sorry, i don't agree.  

And then:

> 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".

IJ: I still don't understand how 12.3 is a special case of
12.1. Checkpoint 12.1 says conform to WCAG 1.0, which says
nothing about what needs to be documented for a user agent
that conforms to UAAG 1.0.

> 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.

The WG resolved at the 19 April 2001 teleconference to
adopt this proposal to address the issue about 12.5 referring
to more than one release:
  http://lists.w3.org/Archives/Public/w3c-wai-ua/2001AprJun/0034

> 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.  

[Editorial]

IJ: I think that if we change "product documentation" in 12.1 to
"user agent documentation" then we will be covered. The
conformance section binds the term "user agent" in the
checkpoints to the subject of the claim. And therefore, old
documentation (of previous versions) would not satisfy the
requirements.

> 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?

IJ: I still don't agree (or still don't understand; sorry).

> 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.

[Editorial]

IJ: The difference (which I will try to clarify in the document)
is that it's a P1 to describe accessibility features *somewhere*
in the user agent documentation. It's a P2 that those features be
documented in a (dedicated) single section (possibly in addition
to being distributed throughout the documentation).

> 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.

Please refer to my proposal [1] to clarify in Guideline 12 which
features that benefit accessibility must be documented. This is
proposal 21b (not yet reviewed during a teleconference).

[1] http://lists.w3.org/Archives/Public/w3c-wai-ua/2001AprJun/0073


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

Received on Friday, 11 May 2001 18:44:27 UTC