Worthwhile critique from Mathew Thomas

Thu Apr 14 13:52:54 UTC 2005

Not sure I agree with everything said here, but it is still worthwhile 
critique as it indicates may valid points where we need to focus on 
documentation. For brevity I have excerpted the stuff relevant to 
documentation. The full critique can be read at 
http://mpt.net.nz/archive/2005/04/11/ubuntu (if the bandwidth has not been 
exceeded).

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.

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. We don't 
have "documentation bounties" and it is hard to see how authors can make any 
sort of living from open-source. The work of the docteam are much appreciated 
'gifts,' as such, I nor anyone else, has the right to mandate what 
contributors will give. As a result, what we 'need to do' and what we 'want 
to do' are often very different things. Faced with formal approach we lost 
most of our contributors. When we left it informal, we got people willing to 
do things because it was what they wanted to do. I don't entirely agree with 
this approach, the results can be seen in Mathews "most excellent critique," 
but so it was. The docs is svn have only been in development since xmas 2004 
and the whole process of developing them is new to Ubuntu. In six months we 
did allot considering the circumstances. Hopefully this time around we will 
get greater cooperation in the form of contributions and opinions from 
authors, users, developers and Mathew :-)

My comments are below.

Start excerpt
============
The help system

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. 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 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.

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.

Mathew:          * “Desktop”. This makes the unwarranted assumption that 
people will consider the items in Gnome’s panels, for example, to be part of 
the “desktop”, rather than being above or below the desktop.
          * “Applications”. This makes the unwarranted assumption that people 
visiting the top-level help page — that is, people seeking help without 
having started any particular program — will nevertheless know what 
“application” they need to use for the thing they want to do.
          * “Other Documentation”. “Other” is a slippery word: it works only 
if the rest of the categories are already clear, and they’re not.
          * “Man Pages”. Teeheeheehee.
          * “About Ubuntu”. This isn’t help, it’s a manifesto. Nothing wrong 
with manifestos, but they don’t belong on the front page of a help system.

Sean: Correct it was only supposed to show from System > About Ubuntu and 
ended up in Yelp also.

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. Perhaps there is no need for it in Yelp? Perhaps 
we should put it in System > Release Notes

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. Perhaps, instead of calling it "Quick Guide" it should have been 
"Quick Tour." Perhaps, since we have more people on the team now, we can 
apply Methews model for the next version. I doubt it will be one page. In 
general, I think we all agree with Mathew and Corey has pointed out some good 
examples that we can use to base our ideas on.

Mathew:            Part of the problem is that the Guide is greatly caught up 
in its own minutiae. For example, it contains this morsel: “Also in this 
release is the FAQ Guide which was ported from the Ubuntu Wiki to Docbook and 
is now a permanent feature of the Ubuntu documentation project.”

          If you know too much to understand the problem with that sentence, 
here it is again, translated into a simulation of how a regular person would 
understand it: “Also in this spurt is the Worple Guide which was worpled from 
the Ubuntu Worple to Worple and is now a permanent feature of the Ubuntu 
worple worple.”

            I’m one of the 0.000002 percent of humans who are subscribed to 
the Ubuntu Documentation mailing list, and they’re lovely people, but even I 
just don’t care about this kind of administrivia. How will reading this help 
anyone use Ubuntu? It won’t.

Sean: Agreed.

      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. 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.

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.
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.

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.' 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. Something like th e"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. Nice, but a royal 
PITA to implement and maintain when you have a handfull of contributors.

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. My suggestion is 
that Mathew join the docteam and get to understand documentation in context 
of open source better. Sitting on a Mac, looking in, then having a say will 
not give your critique much weight in the long run.

-- 
Sean Wheller
Technical Author
sean at inwords.co.za
http://www.inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050414/32b0eaa9/attachment.pgp>