diff options
| author | Ludovic Courtès <ludo@gnu.org> | 2016-06-16 14:51:49 +0200 |
|---|---|---|
| committer | Ludovic Courtès <ludo@gnu.org> | 2016-06-16 23:50:44 +0200 |
| commit | 762e54b7b476982c007c9da96b3b17476a6f1d93 (patch) | |
| tree | 9df2427a19fbb553d8f01a73718cb89bbd2b51a7 | |
| parent | 1ccb3192419ed4fc88ec1ed6dddb73e0a2283be5 (diff) | |
| download | gnu-guix-762e54b7b476982c007c9da96b3b17476a6f1d93.tar gnu-guix-762e54b7b476982c007c9da96b3b17476a6f1d93.tar.gz | |
doc: Recommend against marketing phrases in descriptions.
* doc/guix.texi (Synopses and Descriptions): Add note about marketing
phrases.
| -rw-r--r-- | doc/guix.texi | 8 |
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 |