On 04 Dec 2002 12:55:50 -0500
Colin Walters <walters@debian.org> wrote:
> http://people.debian.org/~walters/descriptions.html
I do have some differences of opinion, though. It's sad, but there are a
getting to be a fairly large number of DDs who are "attention grabbers".
Just a few days ago, I saw a package description that said something
along the lines of "this is the best package for this purpose" ... and
it certainly wasn't. Even if it was, I think everybody would agree that
that kind of language doesn't belong in a Debian package description.
So, the opening section that talks about advertising and whatnot will
probably give these sorts of people the wrong idea; I'd ammend it to:
Debian package descriptions are the first avenue for you to give your
audience relevant, useful information about your package. When you
attempt to give somebody new knowledge, the key idea is to <em>know your
audience</em>.
Also, I'm not sure I agree with the third paragraph; everything in it is
factual and well-said, but it'd be nice if somebody who *didn't* know
what GTK+ and RAD are could know conclusively, "this is not what I
want". When you're looking for something specific, but don't know the
exact package name, the process of elimination is the best start. I know
I, *personally*, have installed packages which I couldn't immediately
rule out from the package description because I didn't *quite*
understand the jargon.
glade is a bad example for my point, though, because it has a great
description :)
In paragraph five ("So how can we better target these users?"), I'd
s/minimum/appropriate amount/. I've seen bloody jihads in very
well-known projects to give only the "minimum of technical jargon", and
people invariably take it to far. Had they just stressed appropriateness
of the text to the audience, things would have been much more
reasonable.
In paragraph six, ("So far we've mainly discussed the synopsis line"),
I'd s/competition/alternatives/; s/advertisement/good documentation/.
(BTW, if you totally disagree with me about this "advertisement" stuff,
do replace all references to "advertisements" with "good advertisements"
and whatnot :)
Also, in the description template, two spaces are used after a period -
is that standard nowadays? (My understanding was that they were
primarily used for variable-width fonts, where a single space would take
up very little page space. Since the descriptions should be presented in
a fixed-width font (for many reasons, this also includes GUI package
browsers), they're a bit redundant.)
Thanks again :)
Attachment:
pgpH8MKiY0ot3.pgp
Description: PGP signature