[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: description writing guide

Colin Walters wrote:
> I think the package descriptions are a very important product of this
> project.  They're going to be one of the first things people see when
> they use Debian, and their quality directly reflects on the quality of
> Debian.  I've been putting in some random efforts here and there to
> comment on new package descriptions, but I finally sat down and
> committed my thoughts on description writing in a semi-coherent form:
> http://people.debian.org/~walters/descriptions.html

Your emphasis on audiences is very good, but I am leery of the treatment
of package descriptions as advertisements. A package description that
reads like an in-your-face advertisement can suck at being a package
description.  You're right in some ways about the correspondance, but I
think the thing you leave out is that these are "advertisements" that
are aimed at getting only the users who should install a package to
install it, not all users, and that if the "advertisement" gets accross
to someone that this is probably not the package they want, it is also
doing its job.  Particularly if it helps them find the package they _do_
want. These are not features of traditional commercial advertisements.
Insert some mumbling about zero-sum games here.

The easiest problem to point to WRT description-as-advertisement is it
encourages the insertation of useless superlatives into the description,
as you do in the example template when you say "foo is a powerful..".
Look at the uses of powerful in existing descriptions, for example, and
see how many you agree with:

kernel-image-*: lilo is characterised as a powerful bootloader
python2.2-numeric: "powerful multi-dimensional array objects"
tcl8.4: "tcl is .. powerful"
ilisp-doc: "ILISP is a powerful GNU Emacs interface"
teapop: "Powerful and flexible"
snd-dmotif: "powerful sound file editor"
wu-ftpd-academ: "a powerful and widely used FTP server"
angband: "Sauron [...] most powerful of his servants"
clara: "features a powerful GUI"
mc: "A powerful file manager."
ncps: "much more powerful than gitps"
libxpa-dev: "a powerful tool"
latte: "Latte is a simple and powerful language"
python-pygresql: "easy use of the powerful PostgreSQL features"
srecord: "collection of powerful tools"
phpnuke: "a powerful assembly of tools"
clamav: "Powerful antivirus scanner"
libgnomedb0-common: "adds, to the already powerful GDA architecture"
lurker: "with a powerful search engine"
zircon: "Powerful X Internet Relay Chat client"
pspp: "powerful program for statistical analysis"
motor-fribidi: "a powerful editor"
ne: "an easy-to-use and powerful editor"
gentoo: "features a fairly complex and powerful file identification system"
dacode: "Powerful and full-featured news engine"

Er, that's the first 10% of them; enough already. I'm left with the
impression that "powerful" has essentially null meaning in most of these
package descriptions, except perhaps when describing Sauron.

I'd rather that our descriptions were more objective and weren't afraid
to say "hey, if you're looking for a really good <foo> and don't have
specialized needs x y and z, you probably want <bar> instead".

see shy "tcl is .. powerful" jo

Attachment: pgpERNmw9O1gJ.pgp
Description: PGP signature

Reply to: