aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2016-06-16 14:51:49 +0200
committerLudovic Courtès <ludo@gnu.org>2016-06-16 23:50:44 +0200
commit762e54b7b476982c007c9da96b3b17476a6f1d93 (patch)
tree9df2427a19fbb553d8f01a73718cb89bbd2b51a7 /doc
parent1ccb3192419ed4fc88ec1ed6dddb73e0a2283be5 (diff)
downloadguix-762e54b7b476982c007c9da96b3b17476a6f1d93.tar
guix-762e54b7b476982c007c9da96b3b17476a6f1d93.tar.gz
doc: Recommend against marketing phrases in descriptions.
* doc/guix.texi (Synopses and Descriptions): Add note about marketing phrases.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi8
1 files changed, 7 insertions, 1 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index cbecc3e96f..4c8dbd1888 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -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