Re: UA Guideline review, rev. 1

Your Point C was wonderful. I have been going over the document but I really have
to jump back and forth all over the place to understand A. What component things
refer to ( the UI or the technology used or other), B. If the item refers to a
reader like Jaws, A player like Spinner or a browser like IE. And then I have to
go to the techniques to figure out what they really mean. Sounds a bit rough on a
developer who just wants to do the right thing for the product. WE are requiring
them to do extra work.

I would like to suggest a reorganization or allowing the developer to just
address those parts of the document they need rather than requiring them to wade
through every thing.  I know that you could just make a supplement specific to
those areas but do you really think in every day development that any of the
implimenters want to read this entire document?

For example. If I were developing a UI for a browser I don't need the information
on the back end technology (My buddy down the hall working on the back end needs
that) Additionally I don't need any thing that applies to Speech renderers only.

Technical writing techniques for business are different from those in academia.
They are based on the knowledge that most people are under a dead line and will
read the minimal necessary to get the job done. They don't go back and
reinterpret. If they misunderstand the first time you don't get a second chance.
One of the principles of technical writing we should employ here is front
loading. Essentially this is giving the most important information up front. This
is not like an abstract in that it gives the conclusions not an out line of  the
topic. Another is "talk to you audience". I hope in this case it is developers
since they are the ones who will have to implement it. And let me tell you if you
don't already know they may work 80+ hours a week and don't have time, interest,
or attention span for verbose or unclear specifications. (Not that the entire
document is verbose or unclear.)
It would be best to state a specification in a clear concise manner and give a
90% example, note or organize what component(s), and type of agent this refers to
then link to a detailed explanation and detailed examples (pictures would be nice
as well for those items that refer to visual interfaces).

Still wadding through...
Lake

"earl.johnson" wrote:

> Must have been to much turkey this weekend... I re-read General Comments C.
> and D. and they didn't make sense so I've updated them below in hopes they'll
> be clearer. Sorry for any confusion my written confusion caused. Please toss
> out the 11/29 review and  use this one.
>
> Thanks, Earl
>
> ==========
>
> UA Guidelines review, rev. 1
>
> GENERAL COMMENTS
>
> A. While content display capabilities are important it is also
>    important to ensure that the feature control portions of the UA UI
>    are also accessible. The later means things like adjusting
>    properties, getting to a menubar and it's entries, getting to and
>    navigating secondary windows, choosing a location, etc. The
>    guidelines explicitly address the content aspect but only implicitly
>    address the features control aspect. With all the focus on content
>    display there's a real risk that important aspecdts of the rest of
>    the UA will be overlooked. It'd be nice to see the features aspect
>    addressed or called out specifically in applicable guidelines. The
>    guidelines this comment applies to are #2, #5, #7, #10 and perhaps
>    #4. #4 provides a nice example for how this clearness can be
>    achieved.
>
> B. Out of curiosity: Has someone sat down with the Web Content,
>    Authoring Tools, and UA guidelines to verify that the UA guidelines
>    cover all the UA dependencies covered in the Web Content and
>    Authoring Tools guidelines? It would be bad if the Web Content and
>    Authoring Tools guidelines called for things the UA guidelines
>    doesn't touch on.
>
> Adding the forgotten words...
>
> C. The guidelines and checkpoints in the document should stand alone so
>    the reader has a pretty good idea of what they mean without having
>    to rely on the Techniques document to explain what is meant.
>
> Translating what was said originally into English...
>
> D. Sometimes the same basic checkpoint is found in more than one guideline.
>    For example, checkpoints 1.3 and 10.3 seem like they could just as
>    easily be merged into a single checkpoint under guideline #1 or #10.
>    Taken as a whole, the checkpoints can be thought of as a long lists
>    of requirements which, from a development perspective, can be
>    overwhelming. While the checkpoints themselves say nothing about the
>    engineering effort required, I think reducing their number if
>    possible will make the accessibility effort seem like a less
>    daunting one to the developer. So the suggestion is look for
>    opportunities to remove checkpoints whose removal won't effect the
>    guideline's completeness. My review contains a couple candidates for
>    consideration.
>
> SPECIFIC COMMENTS
>
> Section 1.5
>
> A. It's probably beyond the scope of this document and to early but it
>    would be nice if a statement could be made about 508 and what
>    minimum priority level is needed to enable compliance. Since access
>    novices will (hopefully) be using this guideline when they design or
>    redesign their UA, it might be good to add in another short section
>    that gives highlights of or makes general statements about 508, the
>    ADA, and the Telecom Act.
>
> Section 2 - UA Guidelines
>
> Guideline #1
>
> Checkpoint 1.1 - The second sentence should be removed because it feels
> like a design decision. It's a good point though so move it to the note
> or Techniques document.
>
> Guideline #2
>
> A. In the description paragraphs, are there formats from other areas that
>    should be called out? SMIL is mentioned, is there anything from TV
>    or other areas? I'm just wondering because th UA enables all sorts
>    of technology convergence.
>
> Checkpoint 2.3 - I think of speech recognition when I see the term
> natural language. Is that what is meant here? If no, perhaps a better
> description can be provided so the reader doesn't need to leave the
> guidelines to verify what natural language means in the checkpoint.
>
> Checkpoint 2.7 - What if the object isn't video or audio? Is this
> checkpoint just for timed media or does it cover things like graphics
> or interactive objects that say nothing about themselves?
>
> Checkpoint 2.9 - Natural language again. The Techniques document
> suggests this applies to the language that content gets displayed as or
> was written in. Given the speech recognition conotations mentioned in
> 2.3 do you think something besides natural language might be a better
> descriptor?
>
> Guideline #3
>
> A. A number of the checkpoints mention rendering. Should they be under
>    Guideline #10 since it's sub-guideline calls out rendering or should
>    rendering be moved from #10 to this guideline?
>
> Guideline #4
>
> A. Mentioning speech rate and pitch suggests to me the UA is the one
>    providing the audio service.
>    1. Does this aspect of the guideline still hold true if the platform
>       the UA is running on provides the service?
>
>    2. Isn't it the audio service that should provide the control?
>
>    3. Does this mean the UA will need to provide a controller UI for
>       all the audio services the user might have (e.g. different TTS
>       devices)?
>
> Checkpoints for the UI - a major design access problem we run across is
> windows that don't give an object input focus when they're made
> activate. I'm not sure if it should be here or under guideline #7, #8,
> or #9 but a checkpoint should say that a component needs to be assigned
> input focus for the content -and- feature control portions of the UA
> UI. This goes back to my general comment saying the feature control
> aspect of the UA UI needs to be explicitly covered.
>
> Guideline #5
>
> A. From the Authoring Tools Guidelines: "Guideline 7. Ensure that the
>    authoring tool is accessible to authors with disabilities." The
>    first descriptive paragraph for it states: "The authoring tool is a
>    software program with standard user interface elements and as such
>    must be designed according to relevant user interface accessibility
>    guidelines."
>
>    1. While this excerpt doesn't yet specifically cover custom
>       components it does basically say use the platform's UI toolkit
>       when buuilding the authoring tool. I don't see the same clarity
>       in this document. It's important that this document say something
>       similar to: a) use the platform's standard UI components whenever
>       possible and ensure that custom components provide equivalent
>       accessibility information as standard UI components in the same
>       programmatic way or b) ensure UI components not based on a
>       platform's standard UI toolkit provide information and events
>       equivalent to that found in currently available accessibility
>       APIs (i.e. JAAPI and MSAA). My recommendation is this be a new
>       checkpoint(s).
>
>    2. Is this a guideline #4 point instead since it talks about the UI?
>
> B. As noted in the Techniques document Java Accessibility API and MSAA
>    are public APIs. They enable the designer to easily make the feature
>    control aspects of the UA's UI accessible and can be extended to
>    cover many accessibility aspects of the content display. For
>    example, JAAPI directly supports not only buttons and comboboxes but
>    editable text also. But unlike DOM, SMIL, and other W3C specs they
>    aren't mentioned in the main guidelines. Since they are relevant,
>    why aren't the JAAPI and MSAA standards specifically mentioned as
>    examples in this document also?
>
> Checkpoint 5.1 - What API(s) is it refering to?
>
> Checkpoint 5.4 - Should this be moved to guideline #8 since it has to
> do with orienting the user?
>
> Checkpoint 5.5 - How about rewording it to something like "Provide
> programmatic support that enables access to notification of changes..."
> This checkpoint appears to be aimed at situations where an assistive
> technology (AT) is utilized. For performance reasons I think the AT (or
> other UA talking to, the prime UA for that matter) should ask for the
> notification first before the UA starts providing it. The important
> point is to provide programmatic facilities in the UA so an AT or other
> technology has a clear place to go in the UA to let it know that they
> want notification of various events.
>    1. Since it's change oriented shouldn't this one be in guideline #9
>       instead?
>
> Checkpoint 5.6 - This feels like a guideline #6 checkpoint because it's
> aimed at content.
>
> Checkpoint 5.7 - What does this mean from a UA perspective when things
> beyond it's control (e.g. the network) impact the performance? How does
> a developer know what this means as it applies to the UA? How will they
> know when they've successfully achieved this checkpoint? This
> checkpoint should be reworded or a better example cited so what is
> meant is clearer or the checkpoint should be removed.
>    1. General related document comment: the guidelines contain both
>       specific and general guidelines all mixed together. The
>       Techniques document provides clarity on some of the general ones
>       but not all.
>         a. How will the developer know when they have successfully met
>            those guidelines like the above?
>         b. What meaning does the Conformance seal of approval being
>            designed have in situations like this where the determination
>            of successful achievement depends so heavily on how well the
>            developer thinks they've done?
>
> Guideline #6
>
> A. Guidelines #5 & #6 without the checkpoints say the same thing to me.
>    But as I read the descriptions and checkpoints associated with each
>    guideline #5 seems to be oriented towards the feature control aspect
>    of the UA UI and #6 seems to be content display oriented.
>
>    1. The wording of the 2 guidelines should be worked on so it's clear
>       what they cover without the need of looking at the checkpoints to
>       ascertain what they're covering.
>
>    2. If my impressions of #5 & #6 are right then #6 should only contain
>       content oriented checkpoints and #5 should only contain feature
>       control oriented checkpoints.
>
> Guideline #7
>
> A. Comments on guideline wording and descriptive paragraphs
>
>    1. Regarding the sub-guideline: "Provide navigation mechanisms that
>       meet the needs of different users: serial navigation for context,
>       direct navigation for speed, search functions, structured
>       navigation, etc."
>         a. This starts off talking about the user but after the : symbol
>            it talks about techniques in a way that doesn't connect it
>            to the user. What does serial navigation for context and
>            direct navigation for speed mean?
>
>         b. I think everything after the : should be removed (especially
>            since they're better covered in the descriptive paragraphs)
>            or tied better to the user or reworded.
>
>    2. The descriptive paragraphs seem to only talk about content display
>       navigation. Navigating the feature control aspects of the UA's UI
>       should also be specifically covered (see general comment A at the
>       top).  In case the guideline's Note was meant to do this - the
>       Note doesn't make this point clearly.
>
>    3. The Note covers search, navigation, and location of input focus.
>       The input focus shouldn't be mentioned here since it's covered in
>       guideline #8 or the connection between input focus and
>       search/navigation should be made clearer in the Note or
>       descriptive paragraphs.
>
> Guideline #8
>
> A. Regarding the sub-guideline: "Provide information about resource
>    structure, viewport structure, element summaries, etc. that will
>    assist the user understand their browsing context."
>    1. The wording as I read it says it's aimed at the content author not
>       UA. How about the following as a possible clarification
>       alternative: "Enable user to get at content meta data to assist
>       in understanding of browsing context (e.g. resource structure,
>       viewport structure, element summaries, etc.)"
>
>    2. I don't know what is meant by "element summaries." It would be nice
>       to see it touched on explicitly in the descriptive paragraphs or
>       pointed to as a glossary term.
>
>    3. There should be more information on resource structure, viewport
>       structure, and element summaries in the Techniques document as
>       well as what other related structure etc. need to be exposed so
>       that it's clearer to the developer what all they need to do.
>
> B. Keeping with general comment A, it should be stated that both the
>    content display -and- feature control of (rest of) the UI need to
>    clearly show focus.
>    1. For developers using a platform's UI toolkit, it's for them easy
>       to think that the toolkit covers the focus issue however this
>       isn't necessarily so, especially when custom components are
>       utilized, and is something that the developer needs to explicitly
>       verify.
>
> Guideline #9
>
> Checkpoint 9.1 - The "to the user and through APIs" part isn't clear.
> This isn't right either (because not all UAs will have a visual
> display) but "visually and programmatically" seems closer to the point
> it appears to me the checkpoint making.
>    1. I'm confused about the user part because the user gets the
>       information regardless of how the information is made available.
>
>    2. Specifically stating API sounds like the document is prescribing
>       what is necessary to successfully acheive this checkpoint. As
>       nice as it would be to do this, I don't think that's the
>       intention of the document. Stating programmatic allows the
>       developer to choose whether or not an API is the way tthey'll
>       achieve this checkpoint.
>
> Checkpoint 9.2 - I don't understand what this one is telling the
> developer to do. Adding a clarification example and/or working over the
> wording would be helpful.
>
> Guideline #10
>
> A. How about making the descriptive, one sentence paragraph the the
>    sub-guideline? i.e. Replace "Allow users... the software." with "Web
>    users..."
>
>    1. The mention of rendering, mouse, keyboard, the user interface in
>       the guideline makes this guideline feel redundant to others
>       already covered under separate guidelines.
>
> B. General guideline comment: What exactly does input configuration mean?
>    Perhaps this should be defined in the guideline's descriptive
>    paragraph so developers are better able to translate it's meaning
>    into the design of their UA.
>
> Checkpoint 10.3 - I have a problem with this checkpoint because it
> really covers 2 things - what the UA should provide and what it should
> enable - but it doesn't present it that way. Single-key capabilities,
> for example, are directly achievable by a UA however single voice
> command is only possible if the UA provides it's own speech recognition
> engine that the user can configure. Staying with the speech recognition
> example, it may very well be a service provided by the platform which
> the UA knows nothing about (and shouldn't have to). This needs to be
> made clearer in the checkpoint as does what the developer needs to do
> to meet it (they can do single-key but they can only be expected to
> provide programmatic support that lets any input device control it).
>    1. What is the difference between this one and checkpoint 1.3?
>
>    2. If the plan is still to keep this checkpoint basically as it
>       stands then how about:
>         a. Move the second sentence should be moved into the
>            checkpoint's descriptive paragraph because the main point is
>            the change and control part.
>
>         b. Reword the checkpoint to something like "Allow the user to
>            change and control how they interact with the user agent."
>
> Checkpoint 10.4 - What's this checkpoint saying? It's descriptive
> paragraph doesn't add enough clariuty for me. The example is mnemonics
> oriented but what should happen if, for example, speech input is used?
> Confounding this, input configuration suggests to me the method the
> user employs to do input but the example at least is more guideline #8
> or #9 oriented.
>
> Checkpoint 10.5 - How about rewording to something like "Avoid default
> input configurations that conflict with operating system navigation,
> control, and access conventions."
>    1. The access addition pertains to things like using 5 taps of the
>       shift key to do something other than invoke StickyKeys.
>
>    2. The Techniques document should include a mention of the StickyKey,
>       etc. keyboard invocation key sequences also since most desktop
>       platforms provide them these days.
>
> Checkpoint 10.8 - Does this mean reconfigure where components in the
> content display and feature control parts of the UA are?
>    1. This highlights the general difficulty I have with this
>       document - it's not clear when it's talking about the content
>       part and when it's talking about the rest of the UI part. The
>       Techniques document does happen to add partial clarity (it's the
>       feature control part) in this case but the guidelines be clear so
>       they shouldn't have to. Additionally, it's not clear if this
>       means the user should be able to control the actual component
>       layout of the UA.

Received on Tuesday, 30 November 1999 15:45:31 UTC