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

Re: description writing guide

On Wed, 2002-12-04 at 14:38, Joey Hess wrote:

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

Ok, I changed the guide a bit more to emphasize a bit more that
descriptions should also be useful.

> 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..".

Ok, people don't really like the "powerful" sample adjective, apparently

I've dropped it.

> Look at the uses of powerful in existing descriptions, for example, and
> see how many you agree with:

Yeah, I know.

> 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".

Ok, I mentioned that in the guide too.

Reply to: