Re: Packages descriptions review

[Anthony DeRobertis]

A random observation: Every day, a few ITP's come in to -devel, and
often their descriptions need work. If we can't even keep up with the
new packages entering the archive, we don't stand much chance of
catching up with the over 10,000 description backlog already in the archive.

And, I suspect it is far easier to prevent a bad description from
happening in the first place, than fix it after the fact. It also
consumes less time for translators, autobuilders, etc.


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Anthony DeRobertis]

Clément Stenac wrote:

> When several packages have more or less the same goal (in the news case,
> there are many news grabers and local servers), should their
> descriptions include a comparison to the other ones ?

I'd say yes: This information will be /very/ useful to the user.

> 
> I don't think we can ask the maintainers to compare (and keep this
> comparisons up to date) their packages to the similar ones, but I agree
> that in some cases, it could be useful for the user.

After thinking about it for a while, I think a package's description
should list some of the key features that make it different from the
rest of the packages that do similar things. When there is only one
package doing the same thing, this pretty much means comparing them.
When there are a bunch of similar pacakges --- say, text editors ---
then it means listing the things that make this package unique.

Looking back, it's pretty clear that the news fetchers aub, brag, nget,
etc. are in the editor case. Leafnode and sn (sn even mentions leafnode)
and maybe even cnews might be in the other case.

I think it's clear that they need to have some comparison. Read the
descriptions of leafnode and sn, and try and answer the following
hypothetical:

I'm setting up a news server for a small firmw with ten
employees. They are on a DSL line, and do not have in-
house experience administering news servers. Which is
best to install: leafnode, sn, or something else?

You can't answer that without either going out on the web and searching,
or installing each and trying it.


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Clément Stenac]

Hello,

Sorry for not answering earlier.

> OK, I've summarized all (I think) of Policy's requirements on packages
> in the wiki page, together with a cite to the section it came from.
Thanks

> Also, I've completed "news", and would appreciate any feedback.

Please see the webpage for comments ...

This first review raises a question, IMHO.

When several packages have more or less the same goal (in the news case,
there are many news grabers and local servers), should their
descriptions include a comparison to the other ones ?

I don't think we can ask the maintainers to compare (and keep this
comparisons up to date) their packages to the similar ones, but I agree
that in some cases, it could be useful for the user.

What do you think ?

-- 
Clément Stenac


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Manoj Srivastava]

On Mon, 01 Aug 2005 02:52:52 -0400, Anthony DeRobertis
<[EMAIL PROTECTED]> said:  

> Wouter Verhelst wrote:
>> On Sat, Jul 30, 2005 at 08:30:51PM -0400, Anthony DeRobertis wrote:

>> They shouldn't be, as they're not supposed to be complete sentences
>> either (think of it as "package -- short description", as in "foo
>> -- a program to do something", or even "foo -- do something")

> Yeah, I know that argument, and happen to agree with it. I believe
> last time it came up a flamewar^W spirated discussion ensued. Was a
> consensus on that ever reached?

From what I recall, not really. There was a proposal that the
 short description be a noun clause, and that the front ends treat it
 like so; but the front ends were never modified.

> If so, a lot of descriptions violate that consensus, and we should
> find an automated way of checking this (to the extent possible;
> proper nouns do need to be capitalized always).

manoj
-- 
He who invents adages for others to peruse takes along rowboat when
going on cruise.
Manoj Srivastava   <[EMAIL PROTECTED]>  
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Anthony DeRobertis]

Wouter Verhelst wrote:
> On Sat, Jul 30, 2005 at 08:30:51PM -0400, Anthony DeRobertis wrote:

> They shouldn't be, as they're not supposed to be complete sentences
> either (think of it as "package -- short description", as in "foo -- a
> program to do something", or even "foo -- do something")

Yeah, I know that argument, and happen to agree with it. I believe last
time it came up a flamewar^W spirated discussion ensued. Was a consensus
on that ever reached?

If so, a lot of descriptions violate that consensus, and we should find
an automated way of checking this (to the extent possible; proper nouns
do need to be capitalized always).


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Anthony DeRobertis]

OK, I've summarized all (I think) of Policy's requirements on packages
in the wiki page, together with a cite to the section it came from.
Also, I've completed "news", and would appreciate any feedback.


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Clément Stenac]

Hello,

> You must update unreviewed description daily. Checked reviewed
> descriptions again and show changes to the reviewer, if the review ist
> not finished.

Ok, did that. 

Thanks for your suggestions,

-- 
Clément Stenac


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Wouter Verhelst]

On Sat, Jul 30, 2005 at 08:30:51PM -0400, Anthony DeRobertis wrote:
> One more question: Was the question, should short descriptions be
> capitalized? ever decided?

They shouldn't be, as they're not supposed to be complete sentences
either (think of it as "package -- short description", as in "foo -- a
program to do something", or even "foo -- do something")

-- 
The amount of time between slipping on the peel and landing on the
pavement is precisely one bananosecond


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Clément Stenac]

Hello,

> One more question: Was the question, should short descriptions be
> capitalized? ever decided?

The policy does not answer this specific question.

Anyway, for such highly-repetitive and computer-detectable "errors",
it's not a good idea to mark the description as wrong here, it would
make a too high number of affected packages.

The correct method is to compile a list of such very common problems (in
the wiki, for example), decide the best solution for this (in
coordination with -devel and -l10n-english), and ask the lintian
maintainers to add checks for these.

Regards,

-- 
Clément


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Anthony DeRobertis]

One more question: Was the question, should short descriptions be
capitalized? ever decided?


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Anthony DeRobertis]

I've started reviewing the news section, and I'm noticing that I'm
running across descriptions which are OK as-is, but could be better. So
far, Iv'e put in a comment saying how I think it could be approved, but
am clicking "OK". Is that right?


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Michael Bramer]

On Sat, Jul 30, 2005 at 04:08:10PM +0200, Clément Stenac wrote:
> > how will you handel changes in the description (from upstream, aka package
> > maintainer)?
> 
> By comparing all descriptions when we are done. For packages which have
> a new descriptions, a manual review/merge will be needed.

No, this will not work.

We habe 10 and more changes in the description _per_day.

Some are very stupid (like
http://ddtp.debian.net/ddt.cgi?diff1=16963&diff2=953 )
other more complex (like
http://ddtp.debian.net/ddt.cgi?diff1=16966&diff2=2177 )

If you need some weeks for the review of all descriptions (and you
will need more time), you can check this all again.

You must update unreviewed description daily. Checked reviewed
descriptions again and show changes to the reviewer, if the review ist
not finished.

Gruss
Grisu
-- 
Michael Bramer  -- http://www.feuerwehr.kreuzau.de/wiki/
PGP: finger [EMAIL PROTECTED]  -- Linux Sysadmin   -- Use Debian Linux
Frage: Stammt der Begriff UNIX aus einem Dialog zwischen einem Deutschen 
und einem Engländer? - "This is for you nix." -- Andreas (Felix) Kalbitz 


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Clément Stenac]

Hello,

> how will you handel changes in the description (from upstream, aka package
> maintainer)?

By comparing all descriptions when we are done. For packages which have
a new descriptions, a manual review/merge will be needed.

Regards,

-- 
Clément Stenac


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Michael Bramer]

On Fri, Jul 29, 2005 at 11:32:18PM +0200, Clément Stenac wrote:
> >  Someone suggested an announcement should be sent to
> > > d-d-a. What do you think ?
> > 
> > Yes, go to it and find some reviewer.
> 
> Will do...
> 
> > Maybe you should add a 'get a random Description' link on your Page...
> 
> I'm not sure it would be very good, because it's better to review
> related packages together. It's however true that it could probably make
> the whole stuff more attractive.

how will you handel changes in the description (from upstream, aka package
maintainer)?

some changed description from this night:

   changed description from dvorak7min (dvorak7min)
   changed description from libnetclient-ocaml-dev (netclient)
   changed description from libocamlnet-ocaml (ocamlnet)
   changed description from libocamlnet-ocaml-dev (ocamlnet)


Gruss
Grisu
-- 
Michael Bramer  -  a Debian Linux Developer  http://www.debsupport.de
PGP: finger [EMAIL PROTECTED]  -- Linux Sysadmin   -- Use Debian Linux
»A train station is a station where trains stops.
 But what are workstations?«


signature.asc
Description: Digital signature

Re: Packages descriptions review

[Clément Stenac]

Hello,

>  Someone suggested an announcement should be sent to
> > d-d-a. What do you think ?
> 
> Yes, go to it and find some reviewer.

Will do...

> Maybe you should add a 'get a random Description' link on your Page...

I'm not sure it would be very good, because it's better to review
related packages together. It's however true that it could probably make
the whole stuff more attractive.

> and you should add some 'send the new description to the BTS'
> 
> After the two reviewer write a new/better/improved/... description,
> the new description should be send to the BTS as minor bug.

Yes. Actually (I now detailed this on the wiki page), what I tought
could be done is to make available a public patch repository and
announce it soundly. What we can hope is that maintainers will use these
patches, making a bug report useless. Of course, after a few weeks, we
would file bugs.

Regards,

-- 
Clément


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Michael Bramer]

On Fri, Jul 29, 2005 at 08:23:26AM +0200, Clément Stenac wrote:
> > If you go to review all description, please check the technical parts
> > also.
> 
> Sure, thanks for the reminder. I added it to the wiki page

Thanks

> I think the interface is now ready for the work to begin. However, very
> few people replied. Someone suggested an announcement should be sent to
> d-d-a. What do you think ?

Yes, go to it and find some reviewer.

> Anyway, it is possible to start the work with the interested persons
> now...
> I set up a table on the wiki page
> ( http://wiki.debian.net/?PackagesDescriptionsReview ).
> 
> Please register yourself on this page before starting work on a section.

Maybe you should add a 'get a random Description' link on your Page...

> I think we should begin by the desktop packages (x11, gnome, kde, ...).
> I don't think base packages should be given a high priority as people
> don't often want to install them. Libs and devel packages are also lower
> priority IMHO

and you should add some 'send the new description to the BTS'

After the two reviewer write a new/better/improved/... description,
the new description should be send to the BTS as minor bug.

Gruss
Grisu
-- 
Michael Bramer  -  a Debian Linux Developer  http://www.debsupport.de
PGP: finger [EMAIL PROTECTED]  -- Linux Sysadmin   -- Use Debian Linux
Du wei?t doch... jeder hat die Software, die er verdient hat.
  --- Felix von Leitner


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Clément Stenac]

Hello,

> If you go to review all description, please check the technical parts
> also.

Sure, thanks for the reminder. I added it to the wiki page

I think the interface is now ready for the work to begin. However, very
few people replied. Someone suggested an announcement should be sent to
d-d-a. What do you think ?

Anyway, it is possible to start the work with the interested persons
now...
I set up a table on the wiki page
( http://wiki.debian.net/?PackagesDescriptionsReview ).

Please register yourself on this page before starting work on a section.

I think we should begin by the desktop packages (x11, gnome, kde, ...).
I don't think base packages should be given a high priority as people
don't often want to install them. Libs and devel packages are also lower
priority IMHO

Thanks for your help

-- 
Clément Stenac



-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Michael Bramer]

On Tue, Jul 26, 2005 at 08:55:23PM +0200, Clément Stenac wrote:
> Hello,
> 
> Following the recent discussion about packages descriptions (see
> http://lists.debian.org/debian-devel/2005/07/msg01074.html and later),
> and based on Lars Wirzenius' idea, I started working on preparing a
> general review of all package descriptions.

If you go to review all description, please check the technical parts
also.

Thinks like this:
 .
 o Adduser can create new users and groups and add existing users to
   existing groups.
 o Deluser can remove users and groups and remove users from a given
   group.
 .
shoud like this:
 .
  o Adduser can create new users and groups and add existing users to
existing groups.
  o Deluser can remove users and groups and remove users from a given
group.
 .

(see 
http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Description
for more infos)

Gruss
Grisu
-- 
Michael Bramer  -- http://www.feuerwehr.kreuzau.de/wiki/
PGP: finger [EMAIL PROTECTED]  -- Linux Sysadmin   -- Use Debian Linux
"Fuer die einen ist es Windows - für die anderen der laengste Virus der Welt..."


signature.asc
Description: Digital signature

Re: Packages descriptions review

[Clément Stenac]

-qa crosspost removed

> 1) It seems that only two people can comment on an entry. If I see a
> problem that two other people have missed, I can't point it out.
Agreed. I'm going to add a freetext field in the packages detail page
for additional comments and a flag on the list page indicating whether
more comments are available.

> 2) It looks like I can edit other people's observations, possibly by
> accident (by hitting submit after them). Fix (1) and this should go
> away, too.
I didn't actually want to bother setting up a real rights system, and I
think we can trust the few people that will help not to be abusive. As
for the accident, yes, that's a possible risk, the best solution is to
carefully coordinate the work through the wiki. I don't expect dozens of
people anyway :)

I also added a few safeguards: reviewers must be different, you can't
fill review2 if review1 isn't filled.

> 3) It doesn't look like there is a way to comment on the "current
> proposal", only on the original description (and only for two people;
> see above).
Ok, I'll add that

> 4) I notice tags are part of the description shown. Do you intend to
> review the tags as well? This should be clarified on the wiki. If the
> answer is "yes", a link to tags documentation needs to be added.
This was actually a side effect of the filling script. I had thought it
might be a good idea to review tags at the same time, but I think it's
too early for a tags review. The maintainers haven't had a chance to tag
their packages themselves.

> 5) The things to look for needs some work. For example, it needs
> something like "description fails to show how the package fits in with
> related pacakges" (e.g., foo-pgsql vs. foo-mysql. Or many others)
Fixed, feel free to edit.

> PS: Having "Improper english" as a thing to look out for on the Wiki
> page was rather bad looking. Fixed. Same with the incomplete list at the
> top.
Hehe, that's why I said native english speakers would be greatly appreciated 
and why 
several people should review the texts.

Thanks for your feedback,

-- 
Clément


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: Packages descriptions review

[Anthony DeRobertis]

Clément Stenac wrote:

> As explained on the wiki page, a web interface has been created to
> centralize all reviews. It is now working (though it still needs
> improvement and reporting capabilities) and available at
> http://zorglub.diwi.org/pkg-descriptions 
> Please play with it and report any problem / requests you might have
> before we start the actual work.

I notice a few things:

1) It seems that only two people can comment on an entry. If I see a
problem that two other people have missed, I can't point it out.

2) It looks like I can edit other people's observations, possibly by
accident (by hitting submit after them). Fix (1) and this should go
away, too.

3) It doesn't look like there is a way to comment on the "current
proposal", only on the original description (and only for two people;
see above).

4) I notice tags are part of the description shown. Do you intend to
review the tags as well? This should be clarified on the wiki. If the
answer is "yes", a link to tags documentation needs to be added.

5) The things to look for needs some work. For example, it needs
something like "description fails to show how the package fits in with
related pacakges" (e.g., foo-pgsql vs. foo-mysql. Or many others)

PS: Having "Improper english" as a thing to look out for on the Wiki
page was rather bad looking. Fixed. Same with the incomplete list at the
top.


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Packages descriptions review

[Clément Stenac]

Hello,

Following the recent discussion about packages descriptions (see
http://lists.debian.org/debian-devel/2005/07/msg01074.html and later),
and based on Lars Wirzenius' idea, I started working on preparing a
general review of all package descriptions.

This of course represents quite a large amount of work, and the more
people are helping, the faster and better it will be carried out !

A web page has been set up on the Debian wiki :
http://wiki.debian.net/?PackagesDescriptionsReview

If you would like to help, please add yourself on this page (and maybe
drop me a mail).

As explained on the wiki page, a web interface has been created to
centralize all reviews. It is now working (though it still needs
improvement and reporting capabilities) and available at
http://zorglub.diwi.org/pkg-descriptions 
Please play with it and report any problem / requests you might have
before we start the actual work.

The wiki page currently lists a number of traditional problems of the
descriptions that reviewers should be aware of. Feel free to complete or
improve this list. I tried to sum up the discussion about the technical
details and not make it too controversial, if you think more discussion
is needed, please do it on the list, not on the wiki.

Thanks for your help (well, I hope so),

-- 
Clément Stenac

PS: it might not be necessary to keep -qa Cced on answers


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]