PackageDescriptions

This page is about the descriptions presented for Ubuntu packages, as displayed in Ubuntu Software Center.

The problem

When Ubuntu Software Center 2.0 was user-tested on Ubuntu 10.04, all participants found it right away and responded very positively. However, when they looked at the software available to them, they sometimes did not understand the descriptions. The descriptions tend to assume a level of sophistication that most new users don’t have; one of the participants described them as “geeky”.

  • Users do not understand:
    • the concept
    • the multiple flavors 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 on-line.

How to write a good description

The critical first sentence

We don’t need to follow exactly the same style for all kinds of package. For example, descriptions for developer libraries will often be more technical, while games use vocabulary and informality appropriate for their intended audience.

However, any non-technical package might show up in a top-level search, and even technical packages will be only a click away. You can’t assume that, for example, everyone looking at an item in the “Engineering” subsection will be an engineer.

So, at least the first sentence of a description should be understandable and helpful enough to turn away people who got to the package by mistake, without seeming condescending to people who really are interested in it.

What a description should contain

  • In the first paragraph, what you can do with the application.
  • Notable features
  • Supported specialist features (necessarily more technical)
  • Equivalence to applications on other operating systems. Don’t go overboard with this - mention another program 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”.

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

Words and phrases to avoid

Packagers

Looking for something to fix? Search for package descriptions containing one of these discouraging words or phrases. For example:
grep-aptavail "an attempt" | egrep -i "^Package:|an attempt"

allows to

This is not valid English. The usual fix is “lets you”, or sometimes "allows". http://launchpad.net/bugs/608231

an attempt
Be more assertive, or more specific about drawbacks.
front end

Treat the front end as the program, like users will.

informations
Unlike French, in English “information” is a mass noun. It has no plural.
supports
Be more specific. For example, “lets you”, “can use”, “can open”, ”can open and save”, “connects to”, “can convert”.
the user
Try “you”.
this package
Use only if essential to distinguish this package from another one containing part of the same software.
tries to
Be more assertive, or more specific about drawbacks.

See also

How you can help

Copy-editors

Within Ubuntu Software Center, examine the title, summary, and description of an item. Is it concise and helpful? Is the spelling and grammar correct? If it’s a non-geek application, does the description avoid geek language? Is it in the appropriate department? If you find a problem, and you are comfortable diving into code to fix it yourself, follow the distributed development instructions with the app-install-data-ubuntu package to fix problems in an application’s title or summary, or the package itself to fix problems with its description. Otherwise, report a bug with (a) the current text, (b) what needs improving, and (c) your proposed replacement text, and give the bug report the metadata tag.

Packagers

Please look for bugs that people have reported about inappropriate application names or summaries, or package descriptions or departments, and fix them. Thanks for your help.

SoftwareCenter/PackageDescriptions (last edited 2010-12-05 09:54:01 by vish)