RFC: fix summary text for lots of packages

Richard Hughes hughsient at gmail.com
Fri Nov 21 15:43:14 UTC 2008


On Thu, 2008-11-20 at 14:33 +0000, Richard Hughes wrote:
> The packaging guidelines have a single sentence on package summaries:
> https://fedoraproject.org/wiki/Packaging/Guidelines#Summary_and_description
> 
> "The summary should be a short and concise description of the package"

Sorry to keep going on about this,  but this is the contents of the
email I'm about to send to ~50 package maintainers.
_______________________________________________________________

Hi!

You've received this email because you're listed as a maintainer of one
or more packages in Fedora with a "bad summary"[1]. We've been talking
recently about perhaps adding clarification to the package guidelines,
specifically about what a package summary should contain:

Many GUI packaging tools make the summary more prominent than the
package name. The summary is often a better description for the end user
when making 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.

The summary needs to show differentiators that help the user choose
which package to take a look at in more detail. Depending on the type of
package we're looking at some of these should have different
information than others. Libraries should also make clear what
programming language they're useful for in addition to their claim to
fame.

The summary should also be a verb phrase, for example "DVD and CD
authoring software" rather than "Create video DVDs and CDs". For some
packages it may be helpful to expand the package name that is an
acronym, e.g. for the package "gimp", the summary could be "GNU Image
Manipulation Program".

Good summaries:

* Package management framework
* XQuery and XPath 2.0 library for Xerces-C
* Simple video DVD and CD authoring software
* Feature rich media player
* Media Player from the Mozilla Foundation
* Gstreamer based media player
* Customizable media player

Bad summaries:

* System daemon that is a DBUS abstraction layer for package management
(too verbose)
* XQilla is an XQuery and XPath 2.0 library, built on top of Xerces-C
(repeating the program name)
* DeVeDe is a program to create video DVDs and CDs (VCD, sVCD or CVD)
(to much detail)

If you have any questions or just want me to commit a fix and leave you
alone, please feel free to email me back.

Thanks,

Richard

[1] where "bad" is defined by a simple tool written by me, and isn't a
reflection on you as a maintainer. :-)
_______________________________________________________________________

What do you think of that?

Richard.





More information about the fedora-devel-list mailing list