6.2.3. The long description

The long description is the primary information available to the user about a package before they install it. It should provide all the information needed to let the user decide whether to install the package. Assume that the user has already read the package synopsis.

The long description should consist of full and complete sentences.

The first paragraph of the long description should answer the following questions: what does the package do? what task does it help the user accomplish? It is important to describe this in a non-technical way, unless of course the audience for the package is necessarily technical.

The following paragraphs should answer the following questions: Why do I as a user need this package? What other features does the package have? What outstanding features and deficiencies are there compared to other packages (e.g., if you need X, use Y instead)? Is this package related to other packages in some way that is not handled by the package manager (e.g., is this the client for the foo server)?

Be careful to avoid spelling and grammar mistakes. Ensure that you spell-check it. Both ispell and aspell have special modes for checking debian/control files:

  1. ispell -d american -g debian/control
  1. aspell -d en -D -c debian/control

Users usually expect these questions to be answered in the package description:

  • What does the package do? If it is an add-on to another package, then the short description of the package we are an add-on to should be put in here.

  • Why should I want this package? This is related to the above, but not the same (this is a mail user agent; this is cool, fast, interfaces with PGP and LDAP and IMAP, has features X, Y, and Z).

  • If this package should not be installed directly, but is pulled in by another package, this should be mentioned.

  • If the package is experimental, or there are other reasons it should not be used, if there are other packages that should be used instead, it should be here as well.

  • How is this package different from the competition? Is it a better implementation? more features? different features? Why should I choose this package?