Re: Best Practice and HowTos for adding accessibility related information to applications?

[Piñeiro <apinheiro igalia com>]

On 07/24/2012 07:44 PM, Sascha Silbe wrote:
> The only document that contains at
> least some minor hints is the "GNOME Accessibility Developers
> Guide" [2], but all it does is mention two examples [3,4] for
> descriptions and roles.

Unfourtunately all those are somewhat outdated. "Update accessibility
guides" was on our TODO list for a long time. Something that it is
important in order to get new developers helping.

>  The ATK Best Practices wiki page [5] might have
> been what I'm looking for, but it's just a list of things that _should_
> be documented, rather than the documentation itself.

Well it has "DRAFT DRAFT" at the beginning ;) But yes, at this moment it
is a list of things that should be documented. That page was started in
order to document good practices for an accessibility implementation, as
a lot of the required information doesn't fit on ATK documentation
itself, as ATK documentation should be mostly an API reference.

>
> Is there any document I missed and that would tell me what attributes I
> should add to the widgets used in Sugar and what values to give them?

Well you are going in the good path providing names, descriptions and
roles. As I mention below, states are also important.

>
> Some concrete questions I already have:
>
> 1. Which attributes should be translated?
>
>    Gnome#525226 has some discussion about whether accessibility-name
>    and / or accessibility-description should be translated, but there's
>    no conclusion.

I have added a comment to that bug. Anyway to anyone reading the list:
the general rule is that any string that could be presented to the user
should be a translated strings. Action names are a corner case because
those names could be used on some heuristics. Like a voice control
application that want to check if you can "click" on an element. But for
the case of actions, you have atk_action_get_name and
atk_action_get_localized_name.

Anyway it is true that this can be confusing, and that properly the
documentation should be explicit about that.

>
>    What parts of the ATK API should be filled with english texts and
>    what parts should be filled with translated texts? 
See my previous comment.

> How should
>    automated tools (e.g. test suites) discover elements and what texts
>    should tools for users (e.g. screen readers) present to the user?
I guess that are you asking how a test suite could search for a button
with the name "press here please" always. On my previous experiences
with test suites, they are usually run on a controlled environment. And
usually as part of that control, the language is always the same. If
they make tests for other languages, they need to know how each name is
translated. This is usually also easy, because as part of that
"controlled environment" they have access to the translation files.

>
> 2. How should accessible-name and accessible-description be worded?
>
>    The only hint I could locate were two examples [3,4] for
>    accessible-description: "Opens Preferences dialog" 
>
>    Like with other parts of the UI, consistent wording is important to
>    users. If different applications use different tense or different
>    style (active/passive etc.), users can get confused. This is even
>    more true for users with disabilities. Tools (like the test suite I'm
>    going to work on) OTOH can easily cope, they only care about syntax
>    (i.e. string literals), not semantics.

I agree, and in fact this has been fuzzy for a long time. On the last
ATK hackfest we were talking about that, mainly because usually the
tooltip was used as description, when usually are not the same. AFAIR at
that moment we talked about accessible-name, adding accessible-hint (or
something like that), and accessible-description. We also tried to
define all of them. I will search my notes to check if we came to a
conclusion.

Not sure what to say about wording. Probably that fits on the previous
general guide, but properly on a language-specific section ie: I guess
that active/passive is something that only applies to some specific
languages.

>
> 3. What attributes other than accessible-name, accessible-description
>    and accessible-role are usually important to users and what values
>    should they have?

The state of the object are also important (ie: know if a check button
is checked or not)

>
> 4. The description of most attributes on AtkObject [7] is pretty
>    weird. It says the properties are "used to notify that the
>    [attribute] has changed".

Well, it doesn't happens on all properties, but I agree that on the ones
happening is weird. After answering this mail I will open a bug in order
to improve that documentation.

>  What does that mean? 

On GObject each time a property change, it emits the signal "notify", so
you can connect to that signal to know when it changes. So probably that
documentation was just a brain dump of the developer adding that property.

> I would expect signals
>    to be used for change notification, not properties. Do I need to do
>    anything about those or will GTK already handle that for me in all
>    cases?

Yes I think that you don't need to do anything.

Thanks for the feedback.

BR

-- 
Alejandro Piñeiro Iglesias