From 762e54b7b476982c007c9da96b3b17476a6f1d93 Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Thu, 16 Jun 2016 14:51:49 +0200 Subject: 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(-) (limited to 'doc/guix.texi') 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 -- cgit v1.2.3