Worthwhile critique from Matthew Thomas

[Matthew Thomas]

(Sorry this will be misthreaded; my full mailbox missed Sean's message.)

Sean Wheller wrote:
>...
> The real problem I have with what Mathew Thomas is saying, is, that it is all 
> well and good to give critique but, since he is subscribed to the docteam 
> mailing list, it would also be good if he joined us and delivered his ideas 
> during development. It is easy to stand on a box and pull apart final 
> creations, not so easy to actually take part in building them.

That is true. I'm sorry I didn't join the list, say, four months ago, 
when saying "hang on, what should be our end product here" might have 
been useful. But four months ago, I didn't know Ubuntu existed. More 
recently, I saw the stress caused when Corey proposed minor changes to 
the infrastructure, and I concluded that proposing major changes to the 
end product -- especially when I won't have much time to contribute 
myself -- would have been counter-productive at that stage.

> The other issue is that Mathew, with or without intention, seems to miss one 
> very important point. The part of the community developing the docs on a 
> constant basis is small and most of them don't want formal approaches to 
> anything. The contributions come from people who do it for no money.

Anything I do for the documentation project will also be for no money. 
I'm being paid to work on Launchpad, not Ubuntu. But you're right: I do 
miss the point. I don't see that the level of payment, or the formality 
of approach, should have much to do with the intended end product. 
Wikipedia, for example, achieves quite a decent end product with neither 
payment nor a formal approach.

>...
> Mathew: 65. Computerized help systems have to be very, very helpful if people 
> will ever bother using them rather than asking a nearby human. The first step 
> to achieving this level of helpfulness is always being ready for use within 
> about one second of being summoned. Unfortunately, Ubuntu’s help system (on 
> this laptop, at least) takes about eight seconds.
> 
> Sean: It would be helpful to know the hardware platform running on Mathews 
> computer and how many other processes he was running during this test.

It's a Toshiba Satellite with 234.4 MB RAM (according to System Monitor) 
and a 1500 MHz Pentium processor (according to Device Manager). I'm 
running Thunderbird, Epiphany, Gaim, and Gnome Terminal. I'll choose 
"System" > "Help" and time it again ... 11 seconds.

> I have 
> run the same test and have yet to find 8 seconds. One of the systems is a P1 
> with 128MB RAM. My feeling is that Yelp, while having its drawbacks, is 
> comparable with most help systems in the time it takes to load and find 
> information

That is true, but it is also true that I have yet to find a help viewer 
on any system that doesn't suck. (The help system in Windows, for 
example, seems to have gotten worse in every version since Windows 3.1.)

> and while it is not the ideal tool, it is what we have in GNOME. 
> It would be great if some developers actually enhanced and improved Yelp. 
> Alas they do not.

True. My points were about "The help system" in general, not just about 
the help content.

> Mathew:  66. The front page of the help system contains seven items, which are 
> worth examining in detail, because they demonstrate how users and developers 
> — even documentation developers — think about things in different ways.
> 
> Sean: Agreed. They do think in different ways. Personally I would like to 
> extend an invitation to Mathew to please make suggestions.

I did exactly that at the end of that item.

>...
> Mathew:          * “Hoary Release Notes”. Again, this is interesting 
> information, but it’s not help.
> 
> Sean: Not help to who? After an upgrade most people look for the Release Notes 
> to find help on what is new.

That seems reasonable, so why not call it "What's new in Ubuntu 5.04", 
and confine it to that topic? The reason I said "it's not help" was that 
it was written from a programmer's point of view. Here's how a "What's 
new" document might look from a user's point of view:

     What's new in Ubuntu 5.04

     *   Ubuntu now includes program-A that lets you do X, program-B
         that lets you do Y, and program-C that lets you do Z.
         _Program-A help_
         _Program-B help_
         _Program-C help_

     *   Several existing programs have major improvements, including
         Program-P, Program-Q, and Program-R. For more information, run
         a program and choose "What's New?" from its own help.

     *   With some computers, you can now put the computer to sleep to
         save power while you're not using it.
         _How to put your computer to sleep_

     *   Many parts of Ubuntu are faster, including starting up,
         printing, and connecting USB and Firewire devices.

.... And so on. The stuff about being faster can be left to last, because 
it's not something people need to know to be comfortable using the new 
version. The implementation details of each of these features 
("readahead", "grepmap", "Live CD infrastructure", and so on) belong on 
the Ubuntu Web site, not in on-screen help. What's new in the 
installation process, and the "Upgrade Notes", belong only on the Web 
site too; it's no use putting either of those in the help, because if I 
can read the help, I've already upgraded.

>...
> Mathew:          * “Ubuntu Quick Guide”. This is a cool idea, but 
> unfortunately what’s provided is not a quick guide. A quick guide would be 
> one printable page, explaining (a) how to find programs, (b) how to find your 
> files, (c) how to turn off the computer, and (d) how to get more help. 
> Instead, the Ubuntu “Quick Guide” is dozens of pages long.
> 
> Sean: Fair enough. I challenge Mathew to please, in one printable page, 
> explain a-d.

Sure, I'll put that on my to-do list, but as a result you might not see 
it for months. :-) I think there are very good writers on this list who 
could do that anyway.

>...
>       A real help system would have items on its front page like “Connecting 
> to the Internet”, “Using files from Windows”, “Printing”, “Chatting online”, 
> “Playing music”, “Making CDs and DVDs”, and “Troubleshooting”.
> 
> Sean: Mathew assumes that all users are of his psychographic profile and level 
> of computer proficiency.

Not at all. I figured out how to connect to the Internet myself, and in 
doing so realized that it would be beyond most people. I don't have 
files from Windows to transfer, but I recognize that most new Ubuntu 
users will. I don't have a printer, but I recognize that for many people 
a computer is not very useful if they can't print.

The topics I chose were my guesses of the tasks people in general will 
need help with most often. Even if I'm half wrong, I'm more right than 
the current Ubuntu help table of contents.

> In an ideal world help systems would be based on 
> User Groups. So if you are an administrator you would get 'administrative 
> topics' and if you are a user you will get 'user topics.' Unfortunately the 
> help systems today are just not that advanced. So we need to provide context 
> to our help topics.

Perhaps, but don't get carried away. People installing Ubuntu on their 
own computers, or (eventually) buying computers with Ubuntu 
pre-installed, will be both admins *and* users.

> Mathew:  67.  Having said all that, people have become used to the idea that 
> systems designed for browsing will be poorly organized and out of date (which 
> is why search engines are more popular than Web directories, for example), so 
> what they usually do instead is search. Unfortunately, Ubuntu’s help system 
> doesn’t even have a search function.
> 
> Sean: Let's correct that. GNOME Yelp does not have a search function.

And what does Ubuntu use for its help? It uses Yelp. Saying "don't 
worry, part X of our product has problem Y, but it's not our fault 
because X was made by someone else" is not how the market works. Aunt 
Tillie doesn't care whose *fault* it is. (This is probably off-topic for 
the ubuntu-doc list, except inasmuch as members of the list can plead 
with friendly programmers to implement search in Yelp. I wasn't writing 
solely for the benefit of the ubuntu-doc list.)

> Personally, I think we should not use yelp at all, rather stick to HTML and 
> CSS under ANY BROWSER. However, the docteam authors, at the time, wanted Yelp 
> or nothing.

Eh? Not only would a Web browser be slower than Yelp, not only would it 
have an interface far too complicated for a help viewer, but it wouldn't 
even solve the problem of not having a search function.

> Mathew:  68. Inside the help system, help for the majority of programs is 
> written in the form of a book. (For example, and I’m sorry to pick on the 
> Ubuntu Quick Guide one more time, its very first information-containing page 
> says insolently that “admonitions will be found throughout the book”.) Books 
> are useful, but they do not belong in on-screen help systems. On-screen help 
> needs to be written in a different style, with a different tone, and at much 
> shorter length.
> 
> Sean: Yes this is a general problem across all Linux help systems. Help is not 
> really help but a collection of 'User Manuals.' Hence the help system should 
> rather be called 'manual system.'

Renaming it wouldn't solve the underlying problem of the lack of useful 
on-screen help.

> On the otherhand, manuals are a form of 
> help. I think what Mathew wants from a Linux help system is content sensitive 
> help where short texts are shown in tip messages.

Help tips are all well and good, but they're not a substitute for useful 
help in a help viewer. All the tooltips in the world won't help you if 
you're trying to do something in the wrong entire window, for example.

> Something like the "What's this?" in Windows. So if you click a checkbox on a dialog with the "What's 
> this?" you will get a short definition of the checkbox.

Or not. The problem with the Windows approach is that, as often as not, 
you go to the trouble of clicking on two separate things (the [?] button 
then the control), only to get "No help is available for this item". But 
I digress.

>... 
> All in all, Mathew has provided us with valuable input for which, personally, 
> I am gratefull. I do however think that Mathew should, when making critique, 
> place his comments in context of the technology the developers have at hand 
> and the environment in which they are developing. Slating something just 
> because you can, is not productive unless people understand the contexts. 
> Don't get me wrong Mathew, I value input, but as a wise man once said to me, 
> "Don't bring me problems I know about without suggesting a solution." It is 
> easy to look on in and throw in 2c went the work is over.

That's part of why I published it right at the start of a development 
cycle, rather than a couple of weeks before the end of it.

> My suggestion is 
> that Mathew join the docteam and get to understand documentation in context 
> of open source better.

I already understand the context. But, you see, that solution doesn't 
scale. You can't expect all Ubuntu users, or even most Ubuntu users, to 
join the documentation team, better understand "documentation in the 
context of open source", and say "oh, that's why the help isn't useful, 
that's all right then". :-)

> Sitting on a Mac, looking in, then having a say will 
> not give your critique much weight in the long run.

I wrote that item using Ubuntu. I haven't used a Mac since my iBook broke.

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