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

Re: RFC: fix summary text for lots of packages

Richard Hughes wrote:
> On Thu, 2008-11-20 at 16:12 +0100, Ralf Corsepius wrote:
>> On Thu, 2008-11-20 at 09:56 -0500, Bill Nottingham wrote:
>>> Josh Boyer (jwboyer gmail com) said: 
>>>>> It would also be a good idea to have a few "shining examples" for people
>>>>> to copy when creating new packages. When we've done that, I'll start
>>>>> filing bugs.
>>>> Just file bugs for packages you think are overly verbose.  Offer
>>>> alternate summaries in the bug, and a URL to your email for
>>>> rationale.
>>> I'm not sure this scales across 5000 packages. So it would be good
>>> to have at least *something* in the guidelines.
>> Well, the FPG is intentionally lax on %summary's, because we had wanted
>> to avoid getting lot in endless discussions on something which is
>> technically widely meaningness.
> Right, but maybe we could have a soft guideline such as:
> * Summary should aim to be less than 8 words
I generally dislike soft guidelines.  Instead of the Packaging Committee
making a controversial decisions that contributors argue about, it
becomes the individual reviewers and packagers arguing about it on many
separate bugs....

Which is not to say that I wouldn't vote for such a thing, just that I
usually ask:
1) Why can this not be a hard guideline?  (In this case, because it's
something that's better left to the packager).

2) Why should this be part of the review guidelines, then?  (So one GUI
tool can better support its interface).

3) Does number 2 justify the arguments that packagers and reviewers are
going to get into and the bugs that will be opened about them?  I'm not
so certain about this one... then again, I haven't opened up a GUI
package manager for over 6 months so....

What I would put into the Guidelines are the best practices and
suggestions you talk about.  That way the review guidelines stay pretty
much the same but people can refer to the best practices for things that
make a good summary.

So instead of:
*Should*: a summary should aim to be less than eight words

we'd have a paragraph or page that describes the summary:

The summary is used by many GUI tools.  Our main supported GUI tool
makes the summary more prominent than the package name because it is
often a better description for the end user to make a decision about
installing.  To make the user's experience better here, we try to have
short, succinct summaries that don't repeat information in the name.

For instance, a good summary for gnome-power-manager would be "Gnome
Applets for setting power saving features"
The repetition of GNOME is good in this case because the applets *only*
run on the gnome panel.

A good summary for: [continue with other examples]


Attachment: signature.asc
Description: OpenPGP digital signature

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