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

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 :)


> 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 :)


> 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: