Re: description writing guide

[Martin Schulze <joey@infodrom.org>]

Colin Walters wrote:
> Hello,
> 
> 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
> 
> Please have a look at this if you're creating a new package now, and
> fixing packages you currently maintain would be great too :)

Your example lists:

Package: foo
Description: <perform some function, do some task> <for GNOME/KDE/WindowMaker/GNU/Linux>
 foo is a <function> program, designed to help
 you <task>.  <more simple details about task>.  Written for
 the <environment>, it supports <feature1> and <feature2>.
 [..]
 .
 <You can find more information about foo at http://www.foo.org.>

It is a bad practice to repeat the package name as the first word in the
long description.  

Also the URL does not belong into the description but should be
placed in the debian/copyright file instead.

To quote Joey Hess:
  The Description field is not intended to be a random dumping-ground
  for any information that cannot fit into some other field.

Regards,

	Joey

-- 
No question is too silly to ask, but, of course, some are too silly
to answer.   -- Perl book

Please always Cc to me when replying to me on the lists.