Ubuntu Wiki

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

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

• Debian guidelines

• Fedora guidelines

How you can help