[orca-list] Calling all doc writers and nitpickers

[Joanmarie Diggs <joanied gnome org>]

Hey all.

<warning>
This message is long. The executive summary is: Help is hooked up. It's
still a work in progress. I'd love your assistance. If, however, you
rely upon localized help for Orca, now is *not* the time to be pulling
master. I repeat: It is not the time to pull master if you cannot live
with unstable docs. "Unstable" (aka Orca from Master) means just that:
It applies to code and it applies to docs. Unstable means it ain't
production-ready.
</warning>

With that disclaimer out of the way.... Here's what's done:

1. A brand new main page with a bunch of links to "how to" and beginner 
   guides. The bulk of these guides are themselves brand new content.
   Nearly all of them have been written too. I still have to write the
   "Documents" one and the "Form Fields" one. Each is marked with "WRITE
   ME".

2. The main page also points externally to the current stable version of
   the GNOME Desktop Accessibility Guide. I've not yet figured out how 
   to get Yelp to load guide from the installed docs and within Yelp.
   That is on my to-do list. The reason I added this link, and did so at
   the top of the new page, is two-fold: For people who are indeed new
   to GNOME, they should read about things like accessible login and
   desktop shortcuts anyway.  For those of you who pull from master and 
   want the old, localized help content, you can get at it fast enough.

3. The main page also points to a dedicated Preferences guide. The
   Preferences guide is much of the content from the current    
   Accessibility Guide. But it has been updated. "What are Profiles?"
   I hear you asking in the near future. <grins> Stay tuned. That's
   coming very, very soon.

4. The main page also points to a new Commands guide. The Commands
   guide took the original content from the Accessibility guide
   (which was missing a bunch of commands and then some), added all
   the missing commands, and reorganized it by functional topic (you
   want to know how to use structural navigation; not how to use the
   laptop layout). Having said that, eventually I plan to make it so
   that anyone who wants to know how to use the laptop layout can just
   pull up a single, auto-generated page. Mallard magic should make that
   easy.

5. Each class of guide (How To's, Commands, and Preferences) should
   point to one another, so that you can read about what structural
   navigation is, find out what your options are, and then find out
   what keys you need to do it all. I still have to spot check that
   everything points to everything it should.

Here's what remains to be done:

1. In addition to Documents and Form Fields, we need to nuke the
   "check out the wiki to find out how to set up braille" from the
    current accessibility guide and include this information within our
   new help. Doing so will make it easier to find by users and get it
   localized in a bunch of languages that our wiki is not localized in.
   Can I assign writing the braille content to one to one or more of you
   daily braille users? Bonus points for people who use non-Ubuntu-based
   distros. I can reliably set up my braille display in Ubuntu, 
   Guadalinex, and presumably Solaris 11. If there are tricks or  
   differences you face, let's get them documented.

2. Take screen shots of each page of the Preferences dialog (which
   looks vastly different on some pages than is illustrated in the
   current accessibility guide) and add them to the content. I'll
   do that soon. Maybe even next.

3. Cause the help button in each page of the Preferences dialog
   to load the associated Preferences page from the new content.
   I'll do that. I'm also toying with the notion of some sort of
   context-sensitive help whereby pressing Orca+Foo in Firefox
   takes you to Web help or Firefox help, but pressing it in
   an OpenOffice table takes you to a page about OpenOffice and/or
   table reading.

4. Figure out what type of URI will cause a link to the
   accessibility guide to load the accessibility guide within
   yelp. If anyone knows, great; otherwise I'm sure the doc
   team lead will tell me once he answers my ping.

5. Proofread, proofread, proofread. I was looking at one page
   and it looked like I bleed commas rather than blood. I plan to do
   a final run through once we're done, of course. But I will take nit
   reports gladly now. At this point I'm seeing what I should have
   written; not necessarily what I really did write.

In addition to that, here's what I'm wondering:

1. What guides did I miss?

2. What things did I fail to include?

3. What things did I do a crappy job of explaining?

I will also gladly accept new content, and corrections to existing
content. And you don't even have to write it in mallard. Plain text is
awesome. I can mark up mallard in my sleep at this point. Which might
explain the extras commas: Sleep writing. But anyway....

We have a bug open for the user doc rewrite:
https://bugzilla.gnome.org/show_bug.cgi?id=631123

Questions belong on the list; corrections and awesome new content belong
on the bug.

I really, really, really want docs that totally rock and make it much
easier to figure out how to use Orca. Your help, as always, is very much
appreciated!

Thanks in advance and take care.
--joanie