Observations in packaged Ubuntu Documentation (Hoary)

[Matthew Thomas]

matthew.east.ubuntu at breathe.com wrote:
> 
>> I'm developing a hierarchy of topics for Ubuntu Help on the wiki
>> <https://www.ubuntulinux.org/wiki/LocalHelp>.
> 
> these categories look fairly similar to those in the Userguide, which 
> i've started working on recently.

That looks like it's going to be a good document, but -- like the Quick 
Guide -- it's not the sort of document that belongs in on-screen help.

Good on-screen help:
*   won't have a section on installing Ubuntu, because if you can read
     the help, you've already installed it;
*   will avoid making you scroll (in the default window size), and
     especially not in the table of contents
     <http://www.g2meyer.com/usablehelp/gallery/>;
*   won't have a Preface, because the proportion of people looking for
     help who are going to be interested in a Preface is zero;
*   won't have a "Conventions" page, for the same reason;
*   won't have a "Book Organization" page, for the same reason;
*   won't have an "Acknowledgments" page, for the same reason;
*   won't use the first person, like the "Ubuntu Linux Background" page
     does;
*   will avoid having any page longer than about four short paragraphs;
... and so on.

Now, all those things have a place in a printed book. The User Guide may 
be very good as a PDF (found at the top level of the Ubuntu CD, perhaps, 
so people can print it out before they install), and it will share many 
topics with on-screen help. But on-screen help is a different target, 
which needs different content and different style.

> It is intended that a link to the 
> userguide will appear on the front help page.
> To explain further, as i see it the current idea is to write books each 
> of which has a different sort of user base in mind. That way when a user 
> opens the local help, he is not just given the categories that you list 
> on that page, but is given a number of books to choose from, depending 
> on his level of expertise.

I'm sorry, but I really don't think that's a good idea. That would mean, 
every time you opened the help, you have to choose what kind of user you 
are. Remember when in Windows 95 or NT 4.0, the first time you looked at 
the help for a program, it asked you what kind of database you wanted? 
<http://joelonsoftware.com/uibook/chapters/fog0000000059.html> This 
would be even worse, because it wouldn't just be happening the first 
time, it would be happening *every* time.

Even if people could be bothered answering, questions like that don't 
really work. People aren't uniformly novices or experts; they're experts 
in some things, and not in others. And even if they did have uniform 
skill level, asking them what that level was wouldn't work either. Some 
people would give the wrong answers because they were underestimating or 
overestimating their ability. Some people would give the wrong answers 
because they didn't want to admit (even to a computer) that they were 
novices. And some people would give right answers, but not get the help 
they wanted, because we authors had made false assumptions about how 
easy or difficult a particular topic is. Sometimes, if people didn't 
find their answer in one "book", they'd try looking in another, but 
mostly they just wouldn't bother and they'd go to Google instead.

On-screen help should have one, task-based hierarchy, catering for 
everyone. That may be difficult, but that's not a reason to make the 
help good for no-one.

-- 
Matthew Thomas
http://mpt.net.nz/