RFC: fix summary text for lots of packages

[Toshio Kuratomi]

Richard Hughes wrote:
> 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:
> 
Rather than "what a package summary should contain" I'd write "what
makes a good package summary"

> Many GUI packaging tools make the summary more prominent than the
> package name.

I still want to know if "many" is really true.  At least KPackageKit and
yumex do not do this.  "Our default GUI packaging tool" would be
accurate if "many" is not.

> 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

s/verb/noun/

> 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:
> 
s/Good Summaries/Examples/

Add package name as a separate field.  "Package management framework"
might be a good summary for conary but a horrible summary for
createrepo.  I still would like to see individual good summaries next to
bad summaries to show before and after more clearly.

> * 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)
> 
I think some of your examples could use some work.

* System daemon that is a DBUS abstraction layer for package management
* Package management framework

What is a "Package management framework"?  Is it createrepo?  Is it yum,
smart, apt? Is it .rpm or .deb?  In fact, it's none of these.  It's a
service (daemon).  It provides a way for a normal user to install
packages.  It's a backend to GUI front-ends.  That seems to be a
security framework for installing packages.  Or a service allowing
end-users to install packages

* Simple video DVD and CD authoring software
* DeVeDe is a program to create video DVDs and CDs (VCD, sVCD or CVD)

The original summary doesn't mention simple.  Does the program aim for
simplicity?  It mentions VCD, sVCD, and CVD.  Is it aiming for
completeness?  Multiple output formats?  Also, "authoring" is ambiguous.
 Is this a program to create video?  Or is it a program to put video
onto media?

-Toshio

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: OpenPGP digital signature
Url : http://lists.fedoraproject.org/pipermail/devel/attachments/20081121/fbee6c19/attachment.bin