Ubuntu Help: what it should/shouldn't include

[Matthew Paul Thomas]

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.
2.  Ubuntu Help is a help system, not a software directory or
     encyclopedia.

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*.
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
     they're ready.

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

*   "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/