6.2.1. General guidelines for package descriptions

The package description should be written for the average likely user, the average person who will use and benefit from the package. For instance, development packages are for developers, and can be technical in their language. More general-purpose applications, such as editors, should be written for a less technical user.

Our review of package descriptions lead us to conclude that most package descriptions are technical, that is, are not written to make sense for non-technical users. Unless your package really is only for technical users, this is a problem.

How do you write for non-technical users? Avoid jargon. Avoid referring to other applications or frameworks that the user might not be familiar with — GNOME or KDE is fine, since users are probably familiar with these terms, but GTK+ is probably not. Try not to assume any knowledge at all. If you must use technical terms, introduce them.

Be objective. Package descriptions are not the place for advocating your package, no matter how much you love it. Remember that the reader may not care about the same things you care about.

References to the names of any other software packages, protocol names, standards, or specifications should use their canonical forms, if one exists. For example, use X Window System, X11, or X; not X Windows, X-Windows, or X Window. Use GTK+, not GTK or gtk. Use GNOME, not Gnome. Use PostScript, not Postscript or postscript.

If you are having problems writing your description, you may wish to send it along to debian-l10n-english@lists.debian.org and request feedback.