also sprach Philip Ashmore <contact@philipashmore.com> [2011.12.18.0834 +0100]:
> If no one has any more issues with the new long description then
> I'll assume all is well.
Hello Philip,
a long description is neither a text of marketing, nor should it be
a complete list of features. The former can go on a website, the
latter should be found in a README file.
The long description should preemptively provide a user with enough
information so that s/he can make a choice. It should be written
with complete sentences in free text, with an informative, objective
style.
A rough guidelines of questions to be answered across three
paragraphs could be:
1. What is the general purpose of the software in this package, or
the collection of software that this package belongs to?
2. What distinguishes this software from other software? For what
use cases was the software designed?
3. How does this package fit in into a collection (unless it's
a single package)? Are there any other noteworthy things that
the user might need to know to decide for or against a piece of
software?
Compare this to the description you propose in
http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652423#15
utility C/C++ include files
libv3c - a C/C++ library
v3c - a utility program meant to be used in scripts or from the
command line
makefile includes - see v3c's client projects "makefile" for examples
automake/aclocal m4 macros - see v3c's client projects for examples
What you are doing is providing a list of contents. Instead, I would
suggest this:
v3c is a C++ programming toolkit that …. It was written because ….
The intended use cases of v3c are …. Compared to other software
(e.g. example1, example2), it is optimised for ….
This package provides a utility program to interact … and control
….
--
.''`. martin f. krafft <madduck@d.o> Related projects:
: :' : proud Debian developer http://debiansystem.info
`. `'` http://people.debian.org/~madduck http://vcs-pkg.org
`- Debian - when you have better things to do than fixing systems
"the unexamined life is not worth living"
-- platon
Attachment:
digital_signature_gpg.asc
Description: Digital signature (see http://martin-krafft.net/gpg/sig-policy/999bbcc4/current)