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



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




[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]