Documenting Launchpad for Ubuntu users

[Matthew Revell]

On Fri, 2006-12-22 at 22:04 +1300, Matthew Paul Thomas wrote:
> I should clarify here that I'm writing without my Canonical hat on, and 
> I'm not trying to discourage Matthew R at all. :-)

I'm happy to debate my plans; it's important. 

> > 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. :-) 

Including me. My knowledge of Python is limited to "something about
white space" and "immutable tuples" :)

> (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.)

Well, in a commercial setting I'd say it's the writer's job to extract
the information. Otherwise, you just end up with what the developers
think the users need to know :)

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

I think that'd go a long way to solving the very first part of the
problem: i.e. that Ubuntu users get confused by the leap from Ubuntu to
Launchpad.

It doesn't solve the problem that lies in most computer users being
unfamiliar with what a bug is, for example, and why they should report
it. 

> 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?

I'd usually refer to it as support material. It's any material - text,
screencast, etc - located within or outside the UI, that helps the user
to make the most of Launchpad.

Although existing users make up the primary audience, good support
material also has a dual marketing role:

1. it tells potential users what Launchpad would offer them
2. it demonstrates a commitment to the user.

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

My enthusiasm comes from watching support requests fall significantly
following improvements in relevant support material.


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

Fair point. My aim is that people should learn about Launchpad from
within an Ubuntu context. Whether that's on the web or in Yelp, I'm not
too concerned. Yelp initially seemed to make sense but it's relatively
static nature makes it less useful.

> 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__

Looks good to me.

> 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. :-)

:)

-- 
Matthew Revell
Launchpad Marketing, Canonical Ltd.

Telephone: +44 (0)1902 585609
SIP: 2585609 at sipgate.co.uk
Skype: matthewrevell

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20061222/469a2bd1/attachment.pgp>