← Back to team overview

ubuntu-manual team mailing list archive

Re: Improving Package descriptions


Hi guys,

(Digging this up from a few weeks ago.)

On Wed, 2010-07-21 at 15:10 +0200, Matthew Paul Thomas wrote:
> Charline has just forwarded to me the analysis provided to us by the
> researcher who ran the user tests of Ubuntu 10.04. Here's the relevant part:
>     == Packages ==
>     Users do not understand:
>     *   the concept
>     *   the multiple flavours of linux
>     *   the multiple architectures of 32 and 64 bits.
>     Until they understand these things they will not be able to
>     confidently download applications they find online.

This is great feedback. I don't think we currently cover any of these
points sufficiently well. I've filed a bug [1].

> For heavyweight applications, we should consider including system
> requirements. How fast does your computer need to be, and how much
> memory does it need?

Developing quantitative system requirements for software is difficult.
Do we have any reasonably popular packages that have heavy hardware
requirements? We can investigate the issue using those.

> >>       * Equivalence to applications on other operating systems
> Don't go overboard with this -- only if it helps to say that a program
> is "similar to X" (where X is really popular in that genre) or "can open
> documents created using Y".

That's the idea.

> > The first two para should be sufficient for most of the applications.
> > We should probably set a guideline which applications need the rest. 
> > 
> > MPT , your thoughts on setting a standard format for descriptions?
> >...
> With package descriptions, as with a program's help pages, it's probably
> bad to follow a particular template too closely, because it'll make them
> boring.

I'm also strongly against setting a rigid template. The intention would
be to provide guidelines only, with the aim of helping packagers to
write more useful descriptions.

I've created a page of guidelines here [2], as part of the packaging
guide. Edits/comments welcome. We can publicise it when we're happy that
it's useful.



[1] - https://bugs.launchpad.net/ubuntu/+source/ubuntu-docs/+bug/620080
[2] - https://wiki.ubuntu.com/PackagingGuide/Howtos/UsefulDescription

Phil Bull
Book - http://nostarch.com/ubuntu4.htm