Worthwhile critique from Matthew Thomas

[Sean Wheller]

On Friday 15 April 2005 08:23, Matthew Thomas wrote:
> 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.

Changes have to be proposed at the right time. Nobody can expect to walk in 
mid stream and decide everyting is wrong or they can do it better. That 
really demotivates people who have been working for a few months under the 
group consensus and results in current work always changing and never ending.

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

I think we need to compare Apples with Apples. Say Gentoo with Ubuntu. :-)

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

Wow I can't believe it takes that long on your system. Something is not right.

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

Make more ... :-)

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

Good idea. Agreed.

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

Well perhaps you can join us in the design of the next quick guide?

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

Agreed. My point was that the information requirements and topics displayed on 
the first page of a help system should actually be associated with user types 
or groups. Unfortunately it is difficult to exactly understand the different 
types of user profiles we are addressing. When speaking to a Windows user who 
is new to Linux one can assume familiarity with certain aspects of computer 
usage. For example, things like file systems are not of interest to a user of 
this profile. 

However, a user who has never used a computer before, could well find this 
information invaluable. Writing all our books from the perspective of the 
'absolute beginner' is not a good idea since our Windows user will feel 
insulted. Therefore, we must strike a balance. The current method is to 
enable users to access information by way of the categories displayed in the 
first page of Yelp. Admittedly, the category names are less than helpful and 
we should do something we have not done, that being to access the information 
categories and label them correctly. We did not pay any attention to this.

On a technical note we also need to understand how to make the relationship 
between Yelp and Scrollkeeper do what we want it to do, not what it wants to 
do. The whole Yelp/Scrollkeeper thing is far to limiting when it comes to 
creativity and customization IMHO.

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

Not at all. I would go so far as to run a wizard, on first invocation of the 
help system, that asks the user to select the user profile that best matches 
what they feel is their level of proficiency. Based on this selection I would 
present certain help topics with greater prominence than others. From there I 
would enable the user to customize their help environment.

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

No GNOME uses Yelp, KDE uses KHelpCenter (which btw has a search). Ubuntu 
itself does not have to use Yelp.

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

Only if you are loading the whole web browser. I would take certain features 
like the rendering engine and strip down useless features until I have a 
light weight fast app that seamlessly browses the local help system and 
web-based resources.

Indexing and searching is easy to implement in this environment.

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

Interesting ... could you expand on your definition of what is "useful help."

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

I was thinking .... it is good to make suggestions at the start of a release 
based on your experience with the previous release and then at then after the 
release to revisit your suggestions and add some more. The continuity is 
better.

>
> > 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". :-)

Email is not the best medium for this. I was trying to say that with a better 
understanding your input could be of even greater value as it would be able 
to directly target problems in context of the bigger picture. For example, 
your current message is just well the Help system sucks. OK, in principle 
this is true. We agree with you and hence I am engaging with you to extract 
more. What I would like to know, considering the current state of technology 
available to authors, is what other solutions are out there that will solve 
the problems you experienced. Perhaps you know of a new help engine for Linux 
or think that one should be developed. Your knowing of the current help 
system weaknesses presented in context of alternatives, combined with 
solutions that can be implimented now would go a long way to promoting a 
better help user agent for Ubuntu. The more you know the more you can help.

-- 
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/20050415/11544977/attachment.pgp>