Synopsis & description guidelines

[Ludovic Courtès]

Hello!

I wanted to add a note somewhere in the manual about Texinfo markup and
ended up writing a section on synopses and descriptions (see below.)

Comments welcome!

Ludo’.

PS: Bioinfo people: apologies in advance, I just took a random example
    that I hoped would illustrate the point.  :-)


7.6.4 Synopses and Descriptions
-------------------------------

As we have seen before, each package in GNU Guix includes a synopsis and
a description (*note Defining Packages::).  Synopses and descriptions
are important: They are what ‘guix package --search’ searches, and a
crucial piece of information to help users determine whether a given
package suits their needs.  Consequently, packagers should pay attention
to what goes into them.

   Synopses must start with a capital letter and must not end with a
period.  They must not start with “a” or “the”, which usually does not
bring anything; for instance, prefer “File-frobbing tool” over “A tool
that frobs files”.  The synopsis should say what the package is—e.g.,
“Core GNU utilities (file, text, shell)”—or what it is used for—e.g.,
the synopsis for GNU grep is “Print lines matching a pattern”.

   Keep in mind that the synopsis must be meaningful for a very wide
audience.  For example, “Manipulate alignments in the SAM format” might
make sense for a seasoned bioinformatics researcher, but might be fairly
unhelpful or even misleading to a non-specialized audience.  It is a
good idea to come up with a synopsis that gives an idea of the
application domain of the package.  In this example, this might give
something like “Manipulate nucleotide sequence alignments”, which
hopefully gives the user a better idea of whether this is what they are
looking for.

   Descriptions should take between five and ten lines.  Use full
sentences, and avoid using acronyms without first introducing them.
Descriptions can include Texinfo markup, which is useful to introduce
ornaments such as address@hidden or address@hidden, bullet lists, or hyperlinks 
(*note
overview of Texinfo: (texinfo)Overview.).  User interfaces such as ‘guix
package --show’ take care of rendering it appropriately.

   Synopses and descriptions are translated by volunteers at the
Translation Project
(http://translationproject.org/domain/guix-packages.html) so that as
many users as possible can read them in their native language.  User
interfaces search them and display them in the language specified by the
current locale.

   Translation is a lot of work so, as a packager, please pay even more
attention to your synopses and descriptions as every change may entail
additional work for translators.