Re: gnome a11y documentation Re: Forming an Accessibility Steering Committee

["Steve Lee" <steve fullmeasure co uk>]

On 19/12/2007, Willie Walker <William Walker sun com> wrote:
> On a higher level, I think we need to take a bigger picture view of the
> GNOME a11y documentation and consider a big refactor/reset -- it's
> currently spread out over a number of places, with many of these places
> being somewhat outdated and/or unorganized.
>
> What I'd like to see is a main 'jumping off' spot that developers,
> future contributors, and users can start with and then easily end up
> getting to the information they want.  I'd propose that this place is
> the WIKI (http://live.gnome.org/GAP or perhaps a page with a more
> intuitive name http://live.gnome.org/Accessibility).

> I'd also propose that we "clean house": get rid of all the old stuff
> and/or clearly mark it as being an archive.  In addition, we should
> strive to eliminate overlap as much as possible.  We've had a number of
> problems, for example, where people have ended up on AT-SPI
> documentation that is not accurate, mostly because there seem to be a
> number of pages that have been created over time.

As someone who recently went through the process of trying to 'zero
in' on it all as a developer I quite agree. I found many conflicting
sources of various ages (to some extent this a common Open source
problem). For example most people I asked were unsure of the correct
AT-SPI docs to use and I still haven't found a definitive list of
events and their semantics.

I also spent a lot of time making design choices that caused large
problems. AT-SPI has hidden depths that would benefit from easy to
assimilate introductions or 'best practice' guides. Sure the code has
it 'all there' but you often don't see the 'wood for the trees' until
you've learnt the hard way. I'd like to have a11y as easy as possible
for developers and users, so it just works.

The starting point also needs to be big and bold so it is found rather
than web searches which can land you anywhere (perhaps we could SEO it
so it gets found first).

I'd be keen to see the user/dev/content-creator stuff kept pretty
close too. Though they are different needs there is actually overlap
(e.g. devs new to a11y  will want to know how to use it) and it all
needs to stay in synch.

I agree the wiki is the best place as it is open. I'd go for
http://live.gnome.org/Accessibility.

> I think this kind of work really needs a good writer with a good sense
> of how to organize and wordsmith the content.  With this proposed
> refactor, I'd like for a writer to not only help do the work, but also
> help us devise a clear plan for how to maintain the pages and how/where
> new documentation should be added.  For example, assuming a new
> assistive technology comes along (e.g., MouseKeys), I'd like to see a
> plan for how its end user and developer documentation can be quickly
> reached from the 'jumping off' spot.

Yes that makes sense to avoid entropy rapidly encroaching ;-)

I think a key is to make it easy to find the answer to a specific
question as well as providing introductory/conceptual/educational
material for quick orientation and depth understanding. Quite what
structure that takes will be interesting to solve.

> If this makes sense, is this something you can help with?

I'm interested in helping as this is an area I'm getting more 'into'.
However I need to work out a few things for next year.

Brian's wiki page idea sounds like a good starting point.

-- 
Steve Lee
--
Jambu - Alternative Access to Computers
www.fullmeasure.co.uk