Examples of good package summaries

From FedoraProject

Revision as of 19:04, 24 February 2009 by Laubersm (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This is a text of mail sent by Richard to owners of packages that were suspected to have bad summaries. It's a good writeup of what should the summary look like, and I couldn't find comparable text elsewhere in the wiki. It would be a pity if it got lost.

Subject: Requesting your help fixing up some package summaries
From: Richard Hughes <hughsient@gmail.com>
Date: Sat, 22 Nov 2008 15:42:11 +0000

Hi!

You've received this email because you're listed as a maintainer of one
or more packages in Fedora with a "poor summary"[1]. We've been
discussing recently about adding clarification to the package
guidelines, specifically about what makes a good package summary, and I
would like people to fix as many existing packages as possible:

Our default GUI packaging tool makes 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
the package 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 noun 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 examples:

* Package management service
* 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 examples:

* 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)
(too much detail)

Lots of people have already patched the summary in devel. If you've
already patched your package, or think the summary of your package is
fine (or you don't think it can be changed or made better), please
delete this email with my sincere apologies. If you have any questions
or just want me to commit a new summary and leave you alone, please feel
free to email me back and ask me to do it.

Many thanks,

Richard Hughes

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