Package descriptions and making them better
I recently had reason to examine most of the descriptions in the Debian
archive, and, well, they were pretty bad. A statistically significant
number of them weren't even properly formatted according to our own
definitions, and many (maybe even a majority) were grammatically incorrect,
stylistically awkward, or just plain unhelpful.
One thing I'd like to get responses to, which is also buried down at
the bottom of this mail, is the idea of the creation of a
"debian-proofreading" list which new package descriptions could be
(manually or automatically?) submitted to for comments. This might be
especially helpful to people who don't speak English natively.
I'd also like to give a couple of suggestions to people writing or
revising descriptions. These are not intended to be exhaustive or
definitive (of course), but they might be a starting point for improving
the quality of package descriptions.
Another good place to look is the sections in the policy manual dealing
with descriptions; specifically, 5.7. I can't find a reference for
the formatting of descriptions (which might explain a fair number
of the improperly formatted descriptions I've seen..)
In general, the guidelines of good (technical) writing should apply.
Be clear, be concise, be unambigous, be informative, and be correct.
I believe that improving our package descriptions has the potential to
greatly improve the ability of users to find what they're looking for.
(if nothing else, it'll help people who are trying to build saner
categorizations of packages and can't take the time to install
every single one)
- Be aware of how description formatting is defined! Descriptions
are word-wrapped within paragraphs, with blank lines (single periods)
separating paragraphs. If you need explicit formatting, you should
indicate it by indenting the lines that should be formatted literally
with an extra space. More specifically, the following bulleted list
is incorrect.
Description: something with a bulleted list.
This is a bulleted list:
* Item one.
* Item two.
* Item three, which has a long description, so I had to wrap
it over to the next line.
* Item four.
* Item five.
Package frontends are allowed to display this as follows:
This is a bulleted list: * Item one. * Item two. * Item three, which has a
long description, so I had to wrap
it over to the next line.
* Item four. * Item five.
Frontends that you can test this with include aptitude and dselect. I
don't know how the others treat this, but I would assume they do something
similar as well.
It's also not worth it to put lots of effort into formatting your
description so that the right-hand-sides of the lines are in a nice
row like this paragraph (which I have seen some packages do), as
a word-wrapping frontend will make such efforts useless.
- The short and long descriptions should be independent; a user should
be able to read one or the other by itself. The obvious problem here is:
Package: liboj-dev
Description: liboj-dev contains the development files for the Orange
Juice library, which communicates via OJP with standard Orange Juice
mixing machines.
I assume everyone can see the problem here. More subtle is the
problem with this description:
Package: liboj-dev
Description: Development files for the Orange Juice library.
liboj-dev communicates via OJP with standard OJ mixing machines.
The problem here: users do not always read the short description
of a package! In fact, the frontends are not built for this: in dselect,
most of the short description is usually not visible due to screen-width
problems, and while the default aptitude configuration shows the short
description directly above the long one, the Vertical-Split theme
places the long description in a *more* prominent place than the
short one!
In other words, assuming the user will read the short description before
the long description is problematic. In this case, the long description
does not mention what OJ stands for, which means that a prospective
user who is reading only long descriptions will be left in the dark about
that.
- Descriptions should generally make sense to a user who encounters
the package without knowing about it. (this is actually enshrined
in policy IIRC) Thus, the following type of description (which is,
unfortunately, quite common), should be avoided:
Package: libfoo-doc
Description: Documentation for libfoo
This package contains the documentation for libfoo.
The natural question after reading this is, "what's libfoo"?
A good way of dealing with this is:
Package: libfoo-doc
Description: Documentation for the libfoo toaster control library
This package contains the documentation for libfoo.
.
libfoo is a library providing generic access to toasting and
frying external devices.
Similarly, descriptions should provide a basic idea of what the
package does. So this is not so good:
Package: perg
Description: UNG perg and related programs
The UNG familiy of perg utilities may be the "fastest perg in the west".
UNG perg is based on a fast frobulating widgetifier, which allows
speeds up to three times those of standard Unix perg.
Presuming that perg is a utility to parse omelette recipies, the
following would be helpful. (note, by the way, that we don't need
to repeat the package name in the Description, since the user has it
already)
Description: Omellete recipie parsers from UNG
This package contains the UNG family of perg omelette
recipie parsers. The UNG perg utilities may be the
"fastest perg in the west" ... (etc)
- Extra blank lines at the beginning and end of the description
are not the norm, and packages which specify these tend to look
odd to the user browsing through the list. If you think a
package manager should add padding at the top of the description,
file a wishlist bug against the package manager.
- Be aware of common problems with spelling, grammar, and style.
An exhaustive list of these would take more space than I care to
use, or than you will want to read.
The real problem here, I suspect, is that a lot of our maintainers
are simply not native English speakers. Would it be possible to
create a list -- eg, debian-proofreading -- that they could
submit prospective descriptions to for (constructive) comments?
A couple common problems are:
=> When you write a pronoun, make sure that its antecedent is clear!
Eg, I saw a number of descriptions with something like this:
Package: pan-fry
Description: Fryer for pancakes.
It lets you fry pancakes using the BAKEALOT external hardware adaptor.
The "it" is ambiguous; it would be better to say "pan-fry" or, if
you don't want to repeat the package name, "this package".
=> Missing or unnecessary articles:
"This package contains BACON ham baking controller. BACON allows
the use of an external baking device with ham dishes"
The first sentence should be "This package contains *the* BACON...",
since BACON is a specific ham baker.
=> "its" is the possessive form of "it".
"it's" is a contraction of "it is".
Thus, "It's raining" and "I took its wealth" are correct
sentences; "Its raining" and "I took it's wealth" are
comprehensible but sloppy. A reader has to do a double take
at the incorrectly apostrophized word.
The same goes for homonyms (which it's vs its is just a
special and very common case of) -- don't say "their" when
you mean "there", etc.
Daniel
--
/-------------------- Daniel Burrows <dburrows@brown.edu> --------------------\
| "Do you know why the prisoner in the |
| tower watches the flight of birds?" |
| -- Terry Pratchett, _Reaper_Man_ |
\------- (if (not (understand-this)) (go-to http://www.schemers.org)) --------/
Reply to: