Ubuntu Help: what it should/shouldn't include
yannick
sevmek at free.fr
Mon Aug 6 15:24:07 UTC 2007
Hi,
You seems to want the Ubuntu doc to focus more on the desktop and let
upstream deals with applications. This is reasonnable, but raise some
serious issues.
Le mardi 07 août 2007 à 00:05 +1200, Matthew Paul Thomas a écrit :
> Over the past couple of weeks I have noticed people extending Ubuntu
> Help to cover things that perhaps it shouldn't. Examples:
> <http://launchpad.net/bugs/128384>
> <http://launchpad.net/bugs/129189>
>
> 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.
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 (btw, the link is
broken here, 7.04).
e.g. The fisrt page Ubuntu help show the user link directly to online
website too.
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.
>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,...)
> 2. Ubuntu Help is a help system, not a software directory or
> encyclopedia.
>
Taking Ubuntu as a whole, it is a software directory. Ubuntu select
useful softwares in its main repository, provide helpful access to them
through add/remove (and synaptic). It even ranks them. This is really
one of the main feature of Ubuntu (GNU/Linux in general). question is:
How to pick up the right softwares for my personal needs ?
> For example, apply these principles to the Liferea newsreader.
> 1. Liferea has a Help menu. Therefore, people will expect Liferea help
> to be accessed from that Help menu. If Liferea help is put in
> ubuntu-docs instead, most people who need that help *will not find
> it*.
Right.
> 2. Liferea, like dozens of other feed readers, is not installed by
> default. Therefore, just as with those dozens of other feed readers,
> instructions on using Liferea should not be shipped by default.
>
Right. This should be in the Liferea help. Still, users are interested
in the main features Liferea may provide them and may wonder how a
particular feature (like news aggregation on the destop) is provided in
the system (Which program do news aggregation?). 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.
e.g. I bet the new vista live system (which provide news) do not use the
RDF/RSS protocol but its own (but I do not know well the situation
there), thus liferea wont work there.
e.g. in the VoIP area, the well know Skype software use its own
obfuscated protocol. Thus Ekiga or any other VoIP software can't
communicate with it. There is even users who use the name "Skype" rather
than "VoIP", even less people know the name of the main standard here:
SIP. Thus even if they want to use VoIP, they tend to ask for the
windows version of Ekiga, rather than asking for a good SIP client on
Windows.
e.g. in the word precessing area, people often refer to "Word" the well
know software from a firm based in Redmond. In the foreseeable future, I
will just mention the Office Open XML naming from Microsoft deliberate
confusion with OpenOffice.org.
e.g Instant messaging...
etc.
I can easily add tons of exemples in this issue.
A desktop without features provided by applications is nothing. I
suggest to extend the Ubuntu help to cover this issue.
What matters here, is the standards used and the interoperability as
well as naming some good software for each area (and their counterpart
on other system as well). Feature based topics would help users :
news aggregation -> feed readers (naming the technologies RSS/RDF, Atom,
etc.)
Telephony/video conferencing over the internet -> Softphone, naming
technologies like SIP
Word processing -> OpenOffice.org, naming ODF (and compatibility with
Word)
Chat -> Intant messaging naming Jabber (and various well used
proprietary protocols)
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,
"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.
I suggest to promote standards too in this feature based (natural
langage) topics, thus covering interoperability issues.
We cannot just wait the users to guess which technology to use or most
of them will just try to install proprietary softwares on Ubuntu (or
compatible free software with closed protocols). There is a war going on
outside Ubuntu to lock users in proprietary technologies. Giving no
guidance on this issue, will not only confuse users, but will hurt
Ubuntu on the long run.
> Various arguments have been made against these principles. I'll
> paraphrase and discuss these briefly.
>
> * "Program X's help is online, therefore people offline won't see it,
> so we should include extra help in ubuntu-docs." But if Program X
> has a Help menu, people confronted with a Web browser error when
> they explore it won't assume Program X has other help elsewhere on
> the computer; they'll assume it has no help at all. Instead of
> writing help hardly anyone will read, it would be better to spend
> your time encouraging Program X's developers to ship their help as
> packaged help pages.
>
Right.
> * "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, or the wiki might provides some tips useful
for only some users.
e.g. the pwc webcam driver was broken in 6.10, and needed to be install
from the upstream source
e.g. some keyboards don't work fully properly and needs workaround
etc.
e.g. Webcam is a mess (there is tons of topics for webcams in the
forums)
e.g. Audio on GNU/Linux is a mess (how many sound systems ? How many
bugs... :( )
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.
The yelp search system will help in this area. (if it integrate
gracefully with non english wiki too...)
> * "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.
> * "If we don't mention Program X in Ubuntu Help, people searching for
> software for Y-ing their Zs won't know how." This is the most valid
> point, but it still doesn't warrant providing instructions on how to
> use software that *isn't even installed*. 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. But don't
> try to give a comprehensive list; that's what Add/Remove Programs is
> for. And again, don't give help for programs that have their own
> help.
>
I do not believe a searching system like the one synaptic provide (based
on short description) will help cover the standards/protocoles/naming
confusing I talked about previously. Users need an explanation here.
Regards,
Yannick
P.S. : I hope you wont take my words as an offense, I do my best to use
english... :)
> * "Program X doesn't use Yelp." That's unfortunate, but not relevant.
>
> I am not suggesting Ubuntu Help should become much smaller than it is.
> Rather, I think it should concentrate on covering topics that don't
> belong elsewhere. For example, none of these searches return useful
> results in Ubuntu 7.04:
> * "What does the orange square mean?"
> * "How can I type special characters?"
> * "All my windows have gone!"
> * "where do i find my mac address"
> * "What's the difference between Suspend and Hibernate?"
> * "i dont like brown how do i change it"
> * "How do I right-click on a MacBook?"
> * "How do I change the keyboard layout?"
> * "Where is Recycle Bin"
> * "audio profile error"
> * "How can I connect a Windows computer to see its files in Ubuntu?"
> * "How can I connect a Mac to see its files in Ubuntu?"
> * "How do I rearrange the menu?"
> * "How do I set up the volume keys on my keyboard?"
>
> If all those searches return a useful page in position #1 or #2 in
> Ubuntu 7.10, that will be awesome.
>
> Cheers
> --
> Matthew Paul Thomas
> http://mpt.net.nz/
>
>
--
Me joindre en téléphonie IP / vidéoconférence ?
sip:yannick at ekiga.net
Logiciel de VoIP Ekiga : http://www.ekiga.org
http://wiki.ekiga.org/index.php/Which_programs_work_with_Ekiga_%3F
More information about the ubuntu-doc
mailing list