Revamping the help system

[Jeff Schering]

On 6/25/06, Matthew Paul Thomas <mpt at myrealbox.com> wrote:

>
> Arrr, now you're sending me off to find references again:
> *   "We did a usability study once and found that almost no one uses
>      the table of contents to find what they're looking for in the
>      docs. Unfortunately, this is one of the BEST ways to find things."
>      <http://blogs.msdn.com/vstsue/archive/2005/05/24/421546.aspx>
> *   "The Table of Contents is great for reference type Help, but
>      usability tests show that it's not used in user assistance."
>      <http://codeproject.com/dotnet/LHChangesUA1.asp#TOC_Index_Search>
>

The thing with the Microsoft programmer's help is that it has a really
good index which can be filtered. When I was using Visual Studio, I
would say that I was able to find what I was looking for 90% of the
time by filtering the index; if i couldn't find it in the index, then
I tried search, and then finally the TOC as a last resort.

As far as I know, we have not indexed any of our docs, so even if yelp
has the ability to show an index and filter on it, that method is
unavailable.

That leaves either the promised-by-edgy useful search or the TOC. But
we can do better than just a TOC, and the descriptive front page as
described by mdke is pretty good, at least for me. I would love to see
that when I open help.

The layout proposed by mdke, with the headings and highlighted links,
is very effective I think. It does not get in the way of the search
for those who want it. And there's usually a time when people want to
explore around, whether it's when they start Ubuntu for the first time
or after a day, a week, or a month or more of use. The front page as
described by Matthew East is an excellent start for that kind of
exploration.

Of course, we can never really know for sure without some useability
testing of our own. (I don't know anything about the testing the Elona
(who works for Julie) did and on what they did the testing... if they
did it on a help system that had a filterable index, then the TOC was
bound to be left unused.)

> So, given that "almost no one" uses the table of contents, how should
> the table of contents be targeted? Should it be a thorough listing of
> topics (like the wiki front page), for the handful of people who are
> willing to browse? I think it can be more helpful to more people by
> trying to save time for a chunk of the people who were on their way to
> the search -- presenting a small number of easily scannable categories,
> preceded perhaps by the three or four most commonly asked questions.
>

The version by Matthew East is effective and easily scannable and does
not get in the way of the search function, which is right at the top.
Both sets of users can be served very well with it. Chopping it down
serves neither group.

> > ...
> >> Preliminary diff attached, though
> >> it's just a start.
> >
> > I've added this as index-mpt.xml so that we can continue brainstorming.
> > ...

index-mpt.xml reminds me of the 80's, when people would take a PC
home, turn it on, and be faced with a blinking cursor and no idea what
to do next. If you make the TOC so information poor and forbidding,
then of course almost no one will use it. The version by mdke (as in
the png on his website, not the one that's in the repos right now) is
very information rich and inviting to the new user, and if the user
doesn't want to be bothered with it and doesn't want to read, then the
search is right there at the top waiting for input.

Cheers,
Jeff

-- 
Jeff Schering
GPG: F23C67E8