Re: description writing guide
On Wed, 2002-12-04 at 14:01, David B Harris wrote:
> 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.
I would tend to agree; however, I don't think that more people will say
stuff like "this is the best package" even if we treat descriptions as a
form of advertising, simply because saying "this is the best" isn't an
effective advertisement. I think it doesn't have a strong effect on
people, because it doesn't say very much. At least, advertisements I
see around me don't use that kind of language. Then again though, I'm
not a marketing department :)
> 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.
Yeah; there's no one hard and fast rule for which acronyms one should
expand in the description; you just have to think about it a bit and
then go with what one thinks is right.
> glade is a bad example for my point, though, because it has a great
> description :)
Yeah.
> 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.
Mmm...OK, I changed it to "a minimal amount of", which doesn't imply it
has to be the absolute minimum, just small.
> 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 :)
Done.
> Also, in the description template, two spaces are used after a period -
> is that standard nowadays?
I think this is an unresolved issue. I've added a section on this to
the description writing guide.
Reply to: