What are we doing wrong?

[Shaun McCance]

On Sun, 2010-01-17 at 10:48 +0000, Phil Bull wrote:
> Hi guys,
> 
> I've been reading the comments in news articles [1][2] about the Ubuntu
> Manual. No-one knows that the system docs exist. Seriously, read them.
> They think that the wiki is the closest thing we have to official docs.
> 
> What are we doing wrong? My hunches are:
> 
>       * People don't think to look in the System menu, or they don't
>         think that clicking the "Help and Support" button will actually
>         be helpful.
>       * People just use Google anyway, because it's faster and they're
>         more familiar with it.
>       * We aren't promoting ourselves enough.
> 
> What do people think?

I want to reply to a few points raised in this thread, but I'd
first like people to take a step back and ask themselves why
they're doing what they're doing.  The only good answer is to
help users.  All too often, we get so wrapped up in what we do
that the documentation itself becomes the goal.  Documentation
is only a means to an end.

With that out of the way, the people who write those articles
about Ubuntu having a manual are unlikely to be the people who
would actually read that manual, except possibly to review it.
Not to downplay good press, but sometimes the things that get
good press aren't the things that are most important.  System
help seems like less of an accomplishment to reviewers.  But
it's not.

That said, there is value in a linear manual.  But only if the
people writing that manual know what its value is, and how it
fits into the big picture of user assistance.  You have to know
who you're writing for and what you're going to write about.
A narrative can engage users and teach them things they would
never try to learn otherwise, but only if it's well planned.

Martin Owens writes:
  People don't often need HELP! they're normally not in a panic
  except when they can't get something fundamental working like
  wifi (and that when they phone people like me in a LoCo team
  for help). What they're after is "learning opportunities",
  "supplemental information", "explanations", better wording
  would go a long way to helping.

No doubt.  And a whole lot of that can and should be done in
topic-oriented help files.  The trick is letting people know
when this information is available, preferably when they're
most likely to want it.  We've talked about better Help menus.
There's also a lot we can do to provide tips in the UI, and
link into the help files for more information.

Martin Owens writes:
  Who would think that Inkscape help could be gotten from
  gnome help?

Probably nobody.  They'll use help buttons and menu items in
Inkscape.  And that's why Yelp's current "tell me what I have
installed" front page is terribly misguided.

Daniel Bo asks:
  Why doesn't Yelp run on first log-in?

Anything that requires you to read the help before using it
is pretty broken.  And I don't think Ubuntu is broken.  So if
they don't need to read it on first login, why should it to
them?  Most people will just be annoyed they had to dismiss
a nagging window.

Remember, the goal is to help users.  That's not necessarily
the same thing as getting them to read the documentation.

One other thing I wanted to mention that didn't fit nicely
as a reply: The Fedora documentation team has been writing
various focused manuals.  Their answer to "how will users
find this?" has been to put links into the Applications
menu.  When you start to look around at what everybody is
doing, you see that we all have many of the same problems.


-- 
Shaun McCance
http://syllogist.net/