Re: [orca-list] [Bug 631123] Orca documentation needs to be updated, converted to Mallard, augmented, and moved to the Orca module

[Joanmarie Diggs <joanied gnome org>]

Hey Steve.

I'm replying to you on the list because your comment is quite valid, but
I think some discussion is in order.

> --- Comment #5 from Steve Holmes <steve holmes88 gmail com> 2010-12-18 10:42:12 EST ---
> When I bring up the main page, the first thing that pops out to me is while
> reading down the page line by line, I come across several sections with
> headings but no indications of anything being a link.  Yet if I go back to the
> top of the same page and press tab, I land on some of these sections.  Actually
> as I right this, I realize these aren't links to something else but I seemed to
> be able to tab to them non the less.  I think what I might be missing here is a
> table of contents.  Most other help manuals seem to start out with a table of
> contents and end up being merely a link farm.  I'm glad the Orca page has
> meaningful content right on the front page.  But I think a table of contents at
> or near the top would be a good help too.

So let me explain my understanding of the Brave New Mallard World,
further clarify what I've done, and then let's discuss.

With Mallard, you have guide pages and topic pages. Guide pages *are*
the table of contents essentially. Topic pages are the ones with actual
text to read.

What's cool about guide pages as opposed to tables of contents is this:
anyone (with the appropriate tools, etc.) can create pages and cause
them to appear on (be interjected within) our guide pages. Some
hypothetical examples:

1. Canonical has decided to go their own way and use unity.
   A guide on how to use unity with Orca would make a lot of sense.
   But it sure as heck does not belong upstream. However, Luke could
   create this page and, without having to modify our existing main
   page or any of our content at all, he could cause this topic to be
   included on our main page as if we put it there ourselves.

2. There are some neat resources out there that are specific to a locale
   (tiflolinux) or a distro (Ubuntu a11y list, Vinux community). I was
   thinking of adding a section on the main page about how to learn more
   and get involved in the Orca community. But that would be about the
   Orca list and the Orca wiki and so on and so forth. What goes on
   elsewhere, while all kinds of awesome, doesn't belong in our upstream
   guide about the Orca community. No worries, local distros can just
   make the pages they need and cause them to appear in the appropriate
   section of our main page.
   
Another thing that's neat about Guide pages is that they can serve as
*augmented* tables of contents. Whereas a table of contents that
included "The Orca Modifier" as a topic would require anyone wondering
what the heck the Orca Modifier is to leave the current page to follow
the link called "The Orca Modifier". If it turned out that is not
something they are interested in, they now have wasted time and need to
backtrack. On the flip side, some people who are looking for that
special key we have might not know it's called the Orca Modifier and
thus might never pursue that topic. Thanks to guide pages,  you can tab
amongst the topic links just like you would a table of contents. But for
any topic/content item you're curious about, you can Down Arrow once to
find out what the topic is about.

Aside from the above, I have been trying to follow what the other
(admittedly few so far) modules have been doing as they switch to
Mallard. I think there is some value in having a consistent look and
feel across all of the GNOME modules. Those other modules aren't making
tables of contents. Again, that's the job of the guide pages.

The one place I differed from those modules -- and this might be the
real problem -- is that I tried to be helpful and included some text on
our guide page to direct people who might need to be directed elsewhere:
To the GNOME Desktop Accessibility Guide, the Orca Preferences dialogs,
and the Orca commands. The other modules don't have helpful text. I'm
thinking that if I remove that helpful text (which maybe isn't so
helpful after all) and find a more guide-page like way to get that
information to the user, our main/guide page will seem more like the
table of contents you seek.

Thoughts?

Thanks for the input!
--joanie