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

[Steve Holmes <steve holmes88 gmail com>]

One thing that did help me get around on that front page was there
seemed to be some header markup before each section so that made
things stand out for me.  Maybe this will take more getting used to
than anything.  I wasn't aware other projects were changing their
formats.  I just recall most gnome helps I've looked at in the past
seemed to almost go overboard with links to links to linked sections
in some cases.  The one thing that got me a bit was I didn't think
some of those sections had any further documentation to go to or if
they did, that link didn't seem obvious to me; I'll need to play with
this further to be sure I know what I'm talking about:).

One other question: I began looking at some of the help panels and ran
into a missing word on one of the files so far.  Would you rather I
just comment on the error in the bug or would you rather have a
patch.  In this case the patch would only have a single word addeddd
or I could hold on to this change and see if there are any others and
roll them into a single patch.  If I decide to patch or if you prefer
such, how can we keep track of who's working on what so we don't come
up and bump heads over the same documents?

On Sat, Dec 18, 2010 at 02:14:13PM -0500, Joanmarie Diggs wrote:
> 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