Ubuntu Help: what it should/shouldn't include

[Matthew Paul Thomas]

On Aug 7, 2007, at 3:24 AM, yannick wrote:
> ...
> Le mardi 07 août 2007 à 00:05 +1200, Matthew Paul Thomas a écrit :
> ...
>> I think there are two important principles here.
>> 1.  Help should be where people expect to find it.
>
> There is no central point for help. Even if Ubuntu desktop has a help
> system, each program has its own help system (man/info pages, yelp
> pages, online help on the software web site, ...), and people often use
> Ubuntu forum, wiki, mailling lists to get help.

Absolutely.

> e.g. run a search in the ubuntu help system, you'll automatically get a
> link in the search result to extend it to online

Yes, I designed that, and Don Scorgie implemented it in Yelp in time 
for Ubuntu 6.10. <http://bugzilla.gnome.org/show_bug.cgi?id=344843>

> (btw, the link is broken here, 7.04).

A new server for search.ubuntu.com has been made available today (due, 
in very small part, to my repeated nagging). Matt Nuzum will work on 
bringing it to life, and I look forward to working on the presentation 
of the search results.

> e.g. The fisrt page Ubuntu help show the user link directly to online
> website too.

Yes, we arranged that so that we would no longer have a "Help" submenu 
containing five items, which was very confusing in Ubuntu 6.06.
<http://mdke.org/?p=11>
<https://wiki.ubuntu.com/HelpAndSupportAccess>

> But Ubuntu tends to have a central points as it provides tools for 
> users to get help, get in touch with the community (Ubuntu help 
> system, the ubuntu wiki, forums, loco teams, etc.). I personally think 
> more
> integration here is the key.

That's right. Integration, not duplication.

> From the user point of view, you tend to split the expectation in 2:
> 1- How to setup/use my desktop, which needs to be covered by the Ubuntu
> documentation, no doubt.
> 2- How can I use x or y feature with Ubuntu (say x is VoIP, news
> agregation, etc.), which you suggest not to be covered by the Ubuntu
> doc, but the software documentation (e.g. Ekiga, Liferea,...)

As I said in my previous message, "If people reasonably expect an 
operating system to have built-in software for Y-ing Zs (such as 
setting up firewalls, or managing photos), it's reasonable to give a 
couple of examples of programs that can do that."

VoIP and news aggregation are both getting close to the point where 
people can reasonably expect an operating system to have built-in 
software for them (cf. Windows Live Messenger, iChat AV, Internet 
Explorer 7, and "Safari RSS"). Therefore, Ubuntu Help should mention 
Liferea and other Ubuntu equivalents, so that people know to install 
them -- but it should not give help on how to use them, because that's 
their job.

On the other hand, nobody reasonably expects an operating system to 
have built-in software for playing poker, and such software is not 
included in Ubuntu by default. Therefore, poker need not be mentioned 
in Ubuntu Help (as it is now). If you want to find software to play 
poker, go to Add/Remove Applications. Same goes for if you want to find 
software to stitch panoramic images, or draw a family tree, or generate 
binaural beats.

> ...
> Stuff here might be even more complex ; sometimes proprietary 
> softwares vendors tend to lock users in their very own technology, 
> leading to problems of interoperability and naming confusion.
> ...

You went into some detail about the issue of proprietary lock-in, but I 
don't understand what any of it has to do with Ubuntu Help. Can you 
explain the connection?

> ...
> e.g. Software descriptions in Synaptic tends to be mostly in english 
> (is fully in english ?) thus non english readers can't use it 
> properly,

Wow, that's an interesting problem. I hadn't thought of that before. 
Have you registered a blueprint for how we could solve it?

I hope you don't think we should solve it by leaving those English 
descriptions glaringly untranslated, but meanwhile including -- in 
Ubuntu Help -- localized descriptions of all 1310 programs available in 
Add/Remove Applications!

> "news reader" or "news aggregation" in synaptic don't shows up Liferea,
> I need to use the right words: "Feed reader". The description here 
> focus on the names technology "RSS/RDF, Atom, etc." which might 
> confuse the user. Well, I'm not sure I'm right here as english isn't 
> my mother
> tongue, but I bet I am.

Have you reported that as a bug in the Liferea package? Again, it would 
be futile to solve that problem by adding a separate description in 
Ubuntu Help, for all 1310 programs available in Add/Remove 
Applications. You'd never finish the job -- and your efforts wouldn't 
show up in the Add/Remove Applications search results anyway.

> ...
>> *   "This help is supplemental to Program X's help, not a
>>     replacement." But "supplemental" doesn't work for help pages,
>>     unless they are directly linked to each other. People will either
>>     find Program X's own help first, and assume those are the only
>>     Program X help pages; or they'll find the ubuntu-docs pages about
>>     Program X, and assume *those* are the only Program X help pages.
>>     Either way, they'll fail to find the rest of the help. And if you
>>     *can* link directly to Program X's own help, then don't duplicate
>>     it -- just link to it.
>
> As I told previously, the Ubuntu yelp system add a link to Ubuntu 
> online documentation (but broken here). This is really useful because 
> sometimes Ubuntu packages needs some workaround to work properly, or 
> upstream might have temporary issue,

Fixing that the right way -- in the help included in the Ubuntu package 
-- is difficult, but it should become easier as the Ubuntu developers 
begin using Bazaar for more packages.

> ...
> The Ubuntu online documentation (wiki) is necessary in this cases
> because the official documentation wont cover those issues (for various
> reasons : in the pwc case, Ubuntu was not aware of it, it was a bug,
> keyboards is just a mess in some cases and might require a very long
> article to cover it for a few users, things may improve quickly...)
>
> The wiki and the help documentation shipped within the system are
> complementary.

That's right.

help.ubuntu.com is the exception to the no-duplication rule, repeating 
everything that's in Ubuntu's packaged help. This is mostly because 
people have become so accustomed to software's packaged help being 
completely useless, that (as Phil Bull said) often they go straight to 
a Web search engine. (Presumably for the same reason, Windows Vista's 
packaged help is mirrored on windowshelp.microsoft.com, and Mac OS X's 
packaged help is mirrored on docs.info.apple.com.) It's also partly 
because it would be weird for help.ubuntu.com to contain pages of 
advanced help, but not the pages of basics upon which the advanced help 
is built.

> The yelp search system will help in this area. (if it integrate
> gracefully with non english wiki too...)

Yes, eventually we should set up localized versions of help.ubuntu.com 
(like the localized versions of wikipedia.org). Then search.ubuntu.com 
can auto-detect your browser languages, and return results written in 
the appropriate languages.

>> *   "Contributing to Program X help upstream is too hard." It may
>>     indeed be harder than contributing to ubuntu-docs. But if Program
>>     X has a Help menu, which leads 20 times as many people to look for
>>     Program X help in its own Help menu rather than in Ubuntu Help (a
>>     conservative estimate, I think), then it's still worth
>>     contributing upstream even if that's 20 times harder than
>>     contributing to ubuntu-docs. As a last resort, get Program X's
>>     help packaged separately using a Launchpad import of the upstream
>>     help. Then you can update the help as fast as you like, and
>>     upstream can merge your changes when they're ready.
>
> Right. That's very important to help upstream.

So ... How can people help you in getting Ekiga help pages packaged 
with Ekiga? :-)

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