Synopsis & description guidelines

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 ‘@code’ or ‘@dfn’, 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.

Re: Synopsis & description guidelines

[Mathieu Lirzin]

ludo@gnu.org (Ludovic Courtès) writes:

> 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.)

Thanks for taking the time to do it!

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

[...]

>    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 ‘@code’ or ‘@dfn’, bullet lists, or hyperlinks (*note
> overview of Texinfo: (texinfo)Overview.).  User interfaces such as ‘guix
> package --show’ take care of rendering it appropriately.

Maybe will it could be useful to indicate that '@' '{' and '}' are
treated specially by giving a cross reference to (info "(texinfo)Special
Characters") ?

>    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.

In the context of package descriptions, will comments extraction work?

  ;; TRANSLATORS: ...
  (description "")

If it's working, it can be interesting to document it.  It would be
useful when usage of obscure terminologies is inevitable.  WDYT?

--
Mathieu Lirzin

Re: Synopsis & description guidelines

[Ludovic Courtès]

Mathieu Lirzin <mthl@openmailbox.org> skribis:

> ludo@gnu.org (Ludovic Courtès) writes:

[...]

>>    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 ‘@code’ or ‘@dfn’, bullet lists, or hyperlinks (*note
>> overview of Texinfo: (texinfo)Overview.).  User interfaces such as ‘guix
>> package --show’ take care of rendering it appropriately.
>
> Maybe will it could be useful to indicate that '@' '{' and '}' are
> treated specially by giving a cross reference to (info "(texinfo)Special
> Characters") ?

Why not.  Would you like to do that?

>>    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.
>
> In the context of package descriptions, will comments extraction work?
>
>   ;; TRANSLATORS: ...
>   (description "")

Yes, see f4e92db.  The string literal must start on the same line as
‘description’.

> If it's working, it can be interesting to document it.  It would be
> useful when usage of obscure terminologies is inevitable.  WDYT?

Hopefully descriptions will rarely use obscure terms, but yes, we could
add a note about it with a xref to xgettext.

Thanks,
Ludo’.