Differences between revisions 12 and 13
Revision 12 as of 2005-07-27 09:01:22
Size: 2758
Editor: anonymous
Comment:
Revision 13 as of 2005-07-27 09:02:15
Size: 2763
Editor: anonymous
Comment:
Deletions are marked like this. Additions are marked like this.
Line 37: Line 37:
 * Stuff not interesting for the usre  * Stuff not interesting for the user
Line 54: Line 54:
 * Good: "Foo is a Python tool to frobnicate baz. It uses libbar."
 * Bad: "Foo is a Python tool which uses libbar. It can frobnicate baz"
 * Worse: "Foo is a Python tool which uses libbar. It can frobnicate baz"
 * Better: "Foo is a Python tool to frobnicate baz. It uses libbar."

Many packages in Debian have low quality descriptions. This affects the general quality of the distribution by making searching difficult.

The idea (first mentioned by Lars Wirzenius in http://lists.debian.org/debian-devel/2005/07/msg01095.html) is to make a general package descriptions review campaign

What needs to be done

All packages descriptions for packages in unstable (maybe only in main) should be reviewed. A large number of common "mistakes" can easily be spotted. Please have a look at the "Things to look for" section.

For descriptions which are identified as problematic, a patch must be elaborated and a wishlist bug filed.

Organization proposal

To ensure maximal quality, all reviews and updates should probably be made by at least two people. Native english speakers are of course appreciated.

A web-based interface has been developed and is available at http://zorglub.diwi.org/pkg-descriptions

Such an interface will (hopefully) allow easy centralization of the current reviews, and reports generation.

For work coordination, a wiki appears to be the best solution, either this one or another one...

Things to look for

In general, anything that does not help or confuse the user is probably worth fixing

Obvious stuff

  • Typos
  • Incorrect English

Other

  • Descriptions that do not really describe what the package does

      The description must include enough details for the user to know what it 
      is about. If the package is related to another one (foo-data, for example), the package does not have to repeat what foo is... but it has to explain how it relates to foo anyway.
  • Hyperbole

      Stuff like "this package is the best in the world"
  • Stuff not interesting for the user
    • "foo was written by me "
    • bar was written while its author had a broken leg"
    • generally speaking, anything too "personal"
  • Incorrect tone

      Many package descriptions are "joking", or are even scornful.
      This should definitely be avoided.

Controversial stuff

  • Technical details about the implementation of the program

A consensus might be that some details are OK/needed, but that should remain reasonable.

Generally speaking, these details should rather be at the end of the descriptions, after describing what the package is/does, or at least not be too intrusive.

  • Worse: "Foo is a Python tool which uses libbar. It can frobnicate baz"
  • Better: "Foo is a Python tool to frobnicate baz. It uses libbar."

Volunteers

If you want to help, please register your name here and/or drop a mail to zorglub _a_t_ diwi _d_o_t_ org

  • Clément Stenac
  • Anthony ?DeRobertis

  • many others (hopefully)

Misc