This is a copy of a document written by Colin Walters. The document has not been updated since Jun 30, 2007 and is likely obsolete. See the internet archive.
Debian package descriptions are basically a form of advertising, although of an informative, useful sort. They're a way to draw users to your package, and in addition convey important details about the package. In advertising, the key idea is to know your audience. This is the overriding principle you should use when writing Debian package descriptions. For example, think about what kinds of people use your package (computer programmers, biologists, musicians, genealogists), the level of computer sophistication they'll have, and the kinds of key words they will look for.
Historically, Debian has had a very technical audience. This is been reflected in all sorts of things in the project, but package descriptions are an obvious aspect. As a consequence, our package descriptions are almost all targeted at technical users, who know GNU/Linux well. They're filled with technical jargon like "GTK+", "X", "binaries", and "GUI". They assume a high level of computer understanding.
In some cases, this isn't a bad thing. Let's take the glade package as an example. Its synopsis line is currently "GTK+ User Interface Builder", and the long description contains "Glade is a RAD tool...". Now, the audience for Glade is definitely going to be mainly composed of people who know what GTK+ and RAD are; computer programmers, who are generally going to have a high level of technical understanding. For them, expanding RAD as Rapid Application Development isn't necessary, although it might not be an altogether bad idea. They'll probably know what GTK+ is.
In contrast, let's examine a package like rhythmbox. In this case, the targeted audience is very general; pretty much anyone who wants to play music on their computer. An example of a bad description would be: "GTK+/GNOME music player like xmms and iTunes". It may help to imagine a friend or relative who isn't very technical looking at the package description. To them, "xmms", "GTK+", and "iTunes" are most likely going to be terms that are just completely meaningless. It's quite possible "GNOME" is too, but we'll visit that issue in a minute. A novice computer user reading this might just skip the package entirely after reading that description, because it looks too challenging. If you're an experienced computer user, this may seem silly, but it really happens!
So how can we better target these users? The answer is to rewrite the description so it makes sense to most users, while maintaining a minimal amount of technical jargon so that it is still useful to advanced users. Here's the current description: "music player for GNOME". In this, the "music player" is featured first. That should draw in all the novices. Now, the intermediate and advanced users can see the "GNOME" at the end, and know that that means it will be well-integrated into their desktop environment. The novice users might not know this term, but they can learn to ignore it (although they will hopefully learn it, like almost all computer users have a vague idea what "Windows" is).
So far we've mainly discussed the synopsis line; all of these same principles apply to the rest of the description as well. However, the long description should take into account that the user has already read the synopsis, and was interested enough to read the rest of the description. That makes it a good place to explain what features it has, how your program is different from the alternatives, etc. In doing this, you should gradually get into more and more detail, just like any other good advertisement would. Again, generally avoid technical terms in the first sentence or first paragraph, but feel free to use them after that.
Again, the above are just guidelines; the principle of know your audience should be the most important guide. For example, the fastdnaml package is quite obviously targeted at biologists. Its synopsis line contains terms like "phylogenetic trees" which are totally meaningless to me, but to a biologist they probably mean something. Thus it's perfectly acceptable for its description to use these terms prominently.
One other note is that while we make the analogy that package descriptions are a form of advertisement, they're also supposed to be as useful as possible. This means that saying things like "This package is the best!!!" isn't really useful. It's doubtful that it is an effective form of advertising either. If another package supports a specialized feature that you don't have yet, it might not be a bad idea to mention it in your description. Remember, the end goal is to help the user.
Take a look at the following checklist, and make sure your description satisfies the criteria1:
Does your description conform to all the guidelines in the Debian Policy?
What does it do (in nontechnical terms)?
Do I need it? (look at the last sentence in the Linux Configure.help descriptions -- they're really helpful if you don't want to understand stuff because you don't need it but need to pick a choice now)
What are outstanding features and deficiencies compared to other packages (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 (this is the client to the foo server)?
Now, let's put all of these guidelines together into a very generic sort of template. You should use creativity here; obviously the below is not even close to a good, real description. It needs to be fleshed out quite a bit.
Package: foo Description: <perform some function, do some task> <for GNOME/KDE/WindowMaker/GNU/Linux> This is a <function> program, designed to help you <task>. <more simple details about task>. Written for the <environment>, it supports <feature1> and <feature2>. . Other features are <feature3> and <feature4>. <more advanced details for technical users>. See the <other package> for more details. . <This package is currently alpha/beta, other stuff...> . <You can find more information about foo at http://www.foo.org.>
There are a few stylistic issues which are still unsolved in the project today; some of them (especially the synopsis line) have been debated at length, with no apparent consensus.
The number of spaces after a full stop - one or two? It seems to me that in general Americans use two spaces, and Europeans use one. However, the consensus reached on debian-devel is that the two spaces have been used to simulate extra space after the end of sentences in fixed-width fonts.
Whether or not the synopsis line should end with a full stop (.); see bug #139957.
Whether or not the beginning of the synopsis line should be capitalized.
Whether or not the description should contain a URL. We really need a separate URL or Homepage field, but until that happens, some people like to have it in the description. However, since the debian/copyright file should contain a URL, other people prefer the description not contain a URL, and instead that we have software automatically extract it from debian/copyright.
1 Thanks to Simon Richter <sjr@debian.org> for most of the checklist.