me/guix
Archived
1
0
Fork 0
Code Activity

doc: Recommend against marketing phrases in descriptions.

Browse source 
* doc/guix.texi (Synopses and Descriptions): Add note about marketing
phrases.
This commit is contained in:
Ludovic Courtès 2016-06-16 14:51:49 +02:00
parent 1ccb319241
commit 762e54b7b4
No known key found for this signature in database
GPG key ID: 090B11993D9AEBB5
1 changed files with 7 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
doc/guix.texi
View file

@ -11172,9 +11172,15 @@ something like ``Manipulate nucleotide sequence alignments'', which
hopefully gives the user a better idea of whether this is what they are
looking for.
@cindex Texinfo markup, in package descriptions
Descriptions should take between five and ten lines. Use full
sentences, and avoid using acronyms without first introducing them.
Please avoid marketing phrases such as ``world-leading'',
``industrial-strength'', and ``next-generation'', and avoid superlatives
like ``the most advanced''---they are not helpful to users looking for a
package and may even sound suspicious. Instead, try to be factual,
mentioning use cases and features.
@cindex Texinfo markup, in package descriptions
Descriptions can include Texinfo markup, which is useful to introduce
ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you