01/03: doc: Recommend against marketing phrases in descriptions.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit 762e54b7b476982c007c9da96b3b17476a6f1d93
Author: Ludovic Courtès <address@hidden>
Date:   Thu Jun 16 14:51:49 2016 +0200

    doc: Recommend against marketing phrases in descriptions.
    
    * doc/guix.texi (Synopses and Descriptions): Add note about marketing
    phrases.
---
 doc/guix.texi |    8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index cbecc3e..4c8dbd1 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.
 
address@hidden 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.
+
address@hidden 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