Documenting Launchpad for Ubuntu users

[Matthew Paul Thomas]

I should clarify here that I'm writing without my Canonical hat on, and 
I'm not trying to discourage Matthew R at all. :-)

On Dec 21, 2006, at 10:46 PM, Matthew Revell wrote:
>
> On Thu, 2006-12-21 at 16:40 +1300, Matthew Paul Thomas wrote:
>
>> Uh oh, that sounds like something I said. :-> I do think that, say, 
>> one hour spent making Launchpad itself more obvious has about the 
>> same
>> benefit as five hours spent documenting it on a separate Web site.
>
> If we choose not to explain Launchpad, that doesn't give us more time 
> to spend on UI design or implementation.

True, particularly for those who aren't Launchpad developers, which is 
most of those on this list. :-) (And taken to the extreme, if 
developers don't even take the time to explain to a writer how the 
software works, the writer can end up just as befuddled as any other 
user, and end up writing help that isn't useful.)

> Also, I'm not sure that UI, however good, would be able to explain the 
> concepts behind Launchpad or its relevance to Ubuntu users.

Well, for example, if I was designing Launchpad, I'd add one sentence 
near the top of <https://launchpad.net/distros/ubuntu/+bugs>: "Ubuntu 
uses Launchpad as its bug tracker." I think that would solve most of 
the problem.

>> The latter is easier, but the former affects 100% of users instead of 
>> just those few who read the documentation.
>
> I think you're making two assumptions that I wouldn't:
>
> - documentation does no more than describe how to use UI
> - the number of users that find documentation useful is small enough to
> be insignificant.
>
> I'm happy to be corrected :)

This is why I try to avoid the word "documentation" in general. Are you 
referring to help (for people using Launchpad already), or to marketing 
(for potential users), or something else?

For help, I'm biased by reading things like "Fear and loathing of the 
Help menu" <http://tc.eserver.org/10347.html> and "a website with a 
help system is usually a failed website" 
<http://www.useit.com/alertbox/20000206.html>. (Those were both written 
before the rise of sophisticated Web applications, and Ubuntu 
contributors may have no choice but to use Launchpad, but that doesn't 
make existing or potential contributors more *willing* to read 
stuff.:-)

> ...
>> I think anything mentioning Launchpad, in the help shipped with 
>> Ubuntu, would be about one paragraph long or so. More detail would 
>> belong on the Web site.
>
> I'd be interested to know what purpose you'd see that paragraph 
> serving.
> ...

Actually, since I wrote that I've discovered 
<https://wiki.ubuntu.com/ContributeToUbuntu>. So I now think there's no 
reason to mention Launchpad in the shipped help at all. If you want to 
contribute to Ubuntu, you are very unlikely to look in the help system 
for guidance; the Web site is much more likely. (Possible lack of 
Internet connection is not an argument against this, because without an 
Internet connection you can hardly contribute anyway. You should still 
be able to download things like the Packaging Guide for offline use, 
though.)

The Web site can also be kept up-to-date much more easily, to match the 
evolving state of the Ubuntu project -- for example, when new community 
projects are established, or when Launchpad's scope or mechanics 
changes. (Such updates aren't necessary for the operating system 
itself, except as part of the bug-fixing process.)

To cater for the rare exceptions, the people who actually do look in 
Yelp for ways to contribute, I suggest moving the current "Contribute 
to Ubuntu" document to the Web site, and in its place in Yelp inserting 
a single page. A first draft:

     Ubuntu has volunteer contributors from all over the world. You
     can help with testing, bug reports, packaging software,
     translating the software into your language, writing, artwork,
     promotion, and even improving these help pages.

     *   __I want to help__

The link would go to the ContributeToUbuntu wiki page (or its 
successor). And from *there* there could be as much information as you 
like about how Ubuntu uses Launchpad. :-)

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