Ubuntu Help: what it should/shouldn't include
Matthew Paul Thomas
mpt at myrealbox.com
Mon Aug 6 12:05:22 UTC 2007
Over the past couple of weeks I have noticed people extending Ubuntu
Help to cover things that perhaps it shouldn't. Examples:
I think there are two important principles here.
1. Help should be where people expect to find it.
2. Ubuntu Help is a help system, not a software directory or
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
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.
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.
* "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.
* "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
* "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
* "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.
Matthew Paul Thomas
More information about the ubuntu-doc