Improving Package descriptions

[Matthew Paul Thomas]

Hi folks

Vishnoo wrote on 07/07/10 18:42:
>
> On Wed, 2010-07-07 at 12:47 +0100, Phil Bull wrote:
>...
>> Do you have any information on what users are typically looking for in
>> a package description? We could guess at their requirements, but I'd
>> prefer to rely on actual feedback if possible.
> 
> Charline Poirer is working on making them available , we should
> probably have it by the end of the week.

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:

    == Ubuntu Software Center ==

    The software centre is highly findable and promises simplicity.

    The categories work well in allowing users to find things that
    are interesting or relevant.

    However, they are then presented with a mix of undifferentiated
    Major Applications and Minor Utilities.

    The quality of the description varies, but they are typically
    feature and technology centric, rather than explaining the
    purpose or value of the software to the user.

    Descriptions, differentiation of apps from utilities, and
    reputation management will all need improving as the software
    centre scales.

    The descriptions tend to make assumptions about a users
    knowledge of a specialised domain that the application addresses.

    ...

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

>>  My guesses would be:
>>
>>       * Broadly, what you can do with the application (simple
>>         description, first para)
>>       * Notable features
>>       * Supported specialist features (necessarily more technical)

That's a good start.

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

>>       * Links to further information and documentation
>
> SC presents a link to homepage as "Website". So we probably dont need
> it in the description.

Right. That's a standard field in the Debian package format, and USC
presents it as a link.

> Interesting idea to link the documentation, maybe MPT could work it
> into his mockup? :
> https://wiki.ubuntu.com/SoftwareCenter#Software%20item%20screen

I don't think it's relevant to offer help on a program that you haven't
installed yet. (Where a walkthrough is more marketing than help, it
should be on the Web site anyway.) And for a program you have installed,
the best place to offer help is inside that program, not inside a
different program.

>>       * Where the application can be started from once installed
>>         (might cause problems between GNOME/KDE/Xfce/etc.)
> 
> https://wiki.ubuntu.com/SoftwareCenter#%E2%80%9CWhere%20Is%20It?%E2%80%
> 9D%20button Should cover that.

We've just been discussing that with Unity developers today.
<https://wiki.ubuntu.com/SoftwareCenter#where-is-it>

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

> 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.
<http://www.google.com/search?q=%22when+you+start+*+the+following+window+is+displayed%22&num=100>

You could improve a *lot* by fixing descriptions just so that these
commands return zero output:

grep-available -is Package,Description -F Description "allows to " |
egrep -i "Package:|allows to "

    (Usual fix: "lets you", or sometimes "allows".)
    <http://launchpad.net/bugs/608231>

grep-available -is Package,Description -F Description "tries to" | egrep
-i "Package:|tries to"

    (Usual fix: be more assertive, or more specific about drawbacks.)

grep-available -is Package,Description -F Description "is an attempt" |
egrep -i "Package:|is an attempt"

    (Again, be more assertive, or more specific about drawbacks.)

grep-available -is Package,Description -F Description "front end" |
egrep -i "Package:|front end"

    (Usual fix: treat the front end *as* the program, like users will.)

grep-available -is Package,Description -F Description "this package" |
egrep -i "Package:|this package"

    (Usual fix: leave the noun implicit. If essential, use "this".)

aisleriot is an example of a package that already has a good
description: "A compilation of over eighty different solitaire card
games. Everything from favorites like Freecell and Klondike through to
the hopelessly pointless Clock Patience." It's brief, to the point, and
light-hearted in keeping with the genre.

avida-qt-viewer is an example of a package that has a poor description:
"avida-qt-viewer is a graphics viewer for the auto-adaptive genetic
system Avida. Avida is a digital world in which simple computer programs
mutate and evolve." It needlessly gives the package name in the first
sentence, it wrongly assumes that you'll know or care that avida-base is
a separate package, and the Web site link doesn't exist any more.

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