Differences between revisions 110 and 111
Revision 110 as of 2005-08-04 12:05:59
Size: 18047
Editor: anonymous
Comment:
Revision 111 as of 2005-08-04 12:09:56
Size: 18050
Editor: anonymous
Comment:
Deletions are marked like this. Additions are marked like this.
Line 203: Line 203:
||contrib/devel ||52 || joewerner || 0%|| || 0%|| ||contrib/devel ||52 || joewerner || DONE || || 0%||

Packages Descriptions review campaign

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, an updated proposal will be elaborated.

Also, it'd be useful to check ITP bug submissions. Let's prevent any further bad descriptions from entering the archive.

Email reports from the list

These packages have been identified as problematic on the list in the thread http://lists.debian.org/debian-devel/2005/07/thrd3.html#01074

(Checked thread up through http://lists.debian.org/debian-devel/2005/07/msg01167.html)

Organization

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

A Web-based interface has been developed to (hopefully) allow easy centralization of the current reviews, and easy generation of reports. It is available at http://zorglub.diwi.org/pkg-descriptions/

Here is how the work will be organized:

  • Reviewers claim sections on this page to avoid conflicts
  • Reviewers use the interface to spot descriptions that need to be fixed
  • A proposal is elaborated.

When we have finished, a repository of the proposed descriptions with attached patches will be made available and an announcement will be sent out.

What we can hope is that maintainers will use this repository to fix their descriptions. After a few weeks, we'll start submitting bugs with suggested patches. (As it will represent a mass bug filing, we'll coordinate with qa).

Things to look for

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

Obvious stuff

  • Typos
  • Speling air-oars. [Sorry!]
  • Awkward punctuation
  • Capitalization errors
  • Incorrect English
    • Word order
    • Compounding
    • Japanese that with which also but. [Sorry!]
  • Diction and style
    • Unclear referents (is it clear what "it", "this", "that", "there" refers to?)
    • Tautology (as in "This package also contains other stuff as well")

Policy violations

See http://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions for full details, but in short:

  • Descriptions which assume you already know about the program. (3.4)
  • Descriptions which do not provide enough information to decide if you want to install the package. (3.4)
  • Descriptions which aren't written in "reverse pyramid" form, with the important details up top. (3.4)
  • Descriptions which do not explain the significant dependencies and conflicts the package declares. (3.4.)
  • Descriptions which include instructions on using or configuring the package. (3.4)
  • Descriptions which include copyright statements or "administrivia." (3.4)
  • Short descriptions which are long, especially over 80 characters. (3.4.1)
  • Short descriptions which include the package name. (3.4.1)
  • Extended descriptions which are continuations of the short description. (3.4.2)
  • Extended descriptions which fail to state what the package does. (3.4.2)
  • Extended descriptions which fail to state how the package relates to the rest of the system. (3.4.2)
  • Extended descriptions which only make sense if you already know about the things the package deals with. Extended descriptions must make sense even to people "who have no idea about any of the things the package deals with." (3.4.2)

The further requirements in http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Description are, in short:

  • Lines starting with a single space are paragraph wrapped.
  • Lines starting with two (or more) spaces are verbatim, and are not wrapped to the extent possible.
  • Lines consiting of space-period are rendered as blank lines.
  • Tab is not allowed (but this is probably something best checked for by machine, so we shouldn't worry here).

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. Also, when there are several versions of a package available, that should be explained. (Example that needs fixing: bash vs. bash-minimal)
  • 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 irrelevant to the decision of installing or keeping the package installed.
  • Inappropriate 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."

Suggestions

  • The package description could explain the main difference/advantage of the package from/over other packages serving the same purpose. Some package descriptions already do so.

Automatically discoverable mistakes

Please list here the most common mistakes you have seen, so their discovery can be automated. For these mistakes, do not mark the package as incorrect. Lintian checks will be added for them.

Rules which can never be broken are best for automated checking. Rules which may indicate that something is wrong, but which will sometimes misfire, are heuristic, and might in the end not be suitable for Lintian checks.

Rules

  • Incorrect case for acronyms
    • GNOME
    • GTK
    • QT, rather than Qt
    • [list others]
  • Possibly some of the spelling errors from below

Heuristics

  • Short description starts with "This" or "It"
  • Short description ends in full stop
  • Short Description Uses Title Case
  • Long descriptions beginning with "It"
  • Short description starts with an upper case letter. (?)
  • Long description starts with a lower case letter.
  • Very common spelling errors
    • Native English / American
      • "definate" pro "definite" (and derivations and inflections, i.e. definitely, definitive, definitively, definiteness ...)
      • "seperate" pro "separate"
      • "grammer" pro "grammar"
      • [list others]
    • Franglish
      • -nnal pro -nal, -nnal(l)y pro -nally
      • [list others]

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 (["zorglub"])
  • Anthony ?DeRobertis

  • Margarita Manterola (["Marga"])
  • Christine Spang
  • Alexander Schmehl (["Tolimar"])
  • David Riebenbauer (["DavRieb"])

  • ["era"] eriksson
  • Jeremiah Foster ["jeremiah"]
  • Kevin Kubasik (["kkubasik"])
  • Johannes Werner (["joewerner"])
  • many others (hopefully)

An IRC channel has been created : #debian-descriptions on Freenode. I think it could be useful (and nice, too). Feel free to join

How to use the web interface

(Comments on the tool and ideas for how to improve it can be added to the PackagesDescriptionsReviewTool page.)

First of all, you need to pick a login ID. No authentication is provided, its only use is to know who made reviews.

Now, you can do a proper review, or you can just browse.

Review

Select a section to begin working on. Sections with many packages have been split up into smaller chunks.

  • Remember to mark the section as taken in the table below.

You are then taken to the main review page. For each package, you can enter a status "Ok", or "Needs fixing" and a comment. (Two review fields are provided).

If you want to enter additional comments, work on a proposal, or comment on the current proposal, you need to go to the package details page by clicking the package name.

  • Remember to update the section's status in the table below when you finish.

Browsing

As above, but don't sign up for reviewing, and don't put anything in the Review fields. If you find something to comment on, click on the package name to get to the details page for that package, where you can write free-form comments, etc.

Dividing up the work

Top priority should be given to desktop applications (gnome, kde, x11, ...) Lowest priority sections are libs, devel, ... and generally speaking stuff users don't often search for.

On the other hand, if you are unsure where to begin or what to do, perhaps starting out with a small, low-priority section would feel safer. (If you're not feeling ready for it, you don't have to be the first reviewer, though; feel free to just add comments via the "package details" page.)

Large sections have been split up into four pieces. Pick one piece at a time. (Sorry, the tool doesn't tell exactly how large each piece is, so the listed number of packages is just exactly 1/4 of the total.)

Section

Nb packages

1st reviewer

Status

2nd reviewer

Status

admin/1

176

0%

0%

admin/2

176

0%

0%

admin/3

176

0%

0%

admin/4

176

0%

0%

base

151

0%

0%

comm

102

0%

0%

contrib/admin

8

kkubasik

DONE

joewerner

DONE

contrib/comm

3

kkubasik

0%

joewerner

DONE

contrib/devel

52

joewerner

DONE

0%

contrib/doc

15

0%

0%

contrib/games

20

joewerner

DONE

arjen

DONE

contrib/graphics

6

joewerner

DONE

0%

contrib/interpreters

2

joewerner

DONE

0%

contrib/kde

1

0%

0%

contrib/libdevel

4

0%

0%

contrib/libs

34

0%

0%

contrib/mail

14

0%

0%

contrib/math

3

joewerner

DONE

kkubasik

0%

contrib/misc

12

0%

0%

contrib/net

15

0%

0%

contrib/otherosfs

22

0%

0%

contrib/perl

2

0%

0%

contrib/python

1

0%

0%

contrib/science

2

joewerner

DONE

kkubasik

0%

contrib/sound

8

0%

0%

contrib/text

22

davrieb

95%

kkubasik

0%

contrib/utils

10

0%

0%

contrib/web

11

0%

0%

contrib/x11

12

0%

0%

devel/1

332.75

0%

0%

devel/2

332.75

0%

0%

devel/3

332.75

0%

0%

devel/4

332.75

0%

0%

doc/1

231.25

0%

0%

doc/2

231.25

0%

0%

doc/3

231.25

0%

0%

doc/4

231.25

0%

0%

editors/1

55

0%

0%

editors/2

55

0%

0%

editors/3

55

0%

0%

editors/4

55

0%

0%

electronics

63

unknown

0%

0%

embedded

9

era

DONE

0%

games/1

168.75

0%

0%

games/2

168.75

0%

0%

games/3

168.75

0%

0%

games/4

168.75

0%

0%

gnome/1

81

zorglub

90%

kkubasik

0%

gnome/2

81

zorglub

90%

kkubasik

0%

gnome/3

81

zorglub

90%

kkubasik

0%

gnome/4

81

zorglub

90%

kkubasik

0%

graphics/1

87.25

0%

0%

graphics/2

87.25

0%

0%

graphics/3

87.25

0%

0%

graphics/4

87.25

0%

0%

hamradio

75

0%

0%

interpreters/1

114.75

0%

0%

interpreters/2

114.75

0%

0%

interpreters/3

114.75

0%

0%

interpreters/4

114.75

0%

0%

kde/1

69.5

0%

0%

kde/2

69.5

0%

0%

kde/3

69.5

0%

0%

kde/4

69.5

0%

0%

libdevel/1

362.25

0%

0%

libdevel/2

362.25

0%

0%

libdevel/3

362.25

0%

0%

libdevel/4

362.25

0%

0%

libs/1

447.75

0%

0%

libs/2

447.75

0%

0%

libs/3

447.75

0%

0%

libs/4

447.75

0%

0%

mail/1

84.75

unknown

0%

0%

mail/2

84.75

unknown

0%

0%

mail/3

84.75

unknown

0%

0%

mail/4

84.75

0%

0%

math/1

61.25

0%

0%

math/2

61.25

0%

0%

math/3

61.25

0%

0%

math/4

61.25

0%

0%

misc/1

109

0%

0%

misc/2

109

0%

0%

misc/3

109

0%

0%

misc/4

109

0%

0%

net/1

282

0%

0%

net/2

282

0%

0%

net/3

282

0%

0%

net/4

282

0%

0%

news

37

anthony

DONE

zorglub

97%

non-free/admin

5

anthony

DONE

era

DONE

non-free/comm

4

anthony

0%

0%

non-free/devel

15

anthony

0%

0%

non-free/doc

48

0%

0%

non-free/editors

2

era

DONE

joewerner

DONE

non-free/electronics

3

joewerner

DONE

0%

non-free/games

34

0%

0%

non-free/graphics

18

0%

0%

non-free/hamradio

2

0%

0%

non-free/libdevel

5

0%

0%

non-free/libs

8

0%

0%

non-free/mail

3

0%

0%

non-free/math

9

0%

0%

non-free/misc

10

0%

0%

non-free/net

13

0%

0%

non-free/news

6

0%

0%

non-free/otherosfs

4

0%

0%

non-free/python

5

0%

0%

non-free/science

16

0%

0%

non-free/sound

7

0%

0%

non-free/tex

8

joewerner

DONE

0%

non-free/text

14

0%

0%

non-free/utils

6

0%

0%

non-free/web

4

unknown

0%

kkubasik

0%

non-free/x11

26

0%

0%

oldlibs

104

0%

0%

otherosfs

98

0%

0%

perl/1

218.25

0%

0%

perl/2

218.25

0%

0%

perl/3

218.25

0%

0%

perl/4

218.25

0%

0%

python/1

176.75

0%

0%

python/2

176.75

0%

0%

python/3

176.75

0%

0%

python/4

176.75

0%

0%

science

143

0%

0%

shells

32

0%

0%

sound/1

109.5

0%

0%

sound/2

109.5

0%

0%

sound/3

109.5

0%

0%

sound/4

109.5

0%

0%

tex

151

0%

0%

text/1

139.75

davrieb

10%

0%

text/2

139.75

0%

0%

text/3

139.75

0%

0%

text/4

139.75

0%

0%

utils/1

188

0%

0%

utils/2

188

0%

0%

utils/3

188

0%

0%

utils/4

188

0%

0%

web/1

219.25

jeremiah

0%

0%

web/2

219.25

jeremiah

0%

0%

web/3

219.25

jeremiah

0%

0%

web/4

219.25

jeremiah

0%

0%

x11/1

184.25

zorglub

0%

0%

x11/2

184.25

zorglub

0%

0%

x11/3

184.25

zorglub

0%

0%

x11/4

184.25

zorglub

0%

0%