Re: [PATCH] doc: The description should not be used as an introduction to generics.

[ng0 <ng0@we.make.ritual.n0.is>]

Lukas Gradl <lgradl@openmailbox.org> writes:

> [ Unknown signature status ]
> ng0 <ng0@we.make.ritual.n0.is> writes:
>
>> From e399e9a982e8a14e4e7f66d5318d3cf7919a81fb Mon Sep 17 00:00:00 2001
>> From: ng0 <ng0@we.make.ritual.n0.is>
>> Date: Fri, 26 Aug 2016 11:16:27 +0000
>> Subject: [PATCH] doc: The description should not be used as an introduction to
>>  generics.
>>
>> * doc/guix.texi (Synopses and Description): Generic terms like
>> "tiling window manager" should not be explained in full length
>> in the description, only explain generic terms when no external
>> resources explain them and if you need to explain them, keep it
>> short and simple.
>> ---
>>  doc/guix.texi | 5 +++++
>>  1 file changed, 5 insertions(+)
>>
>> diff --git a/doc/guix.texi b/doc/guix.texi
>> index 5330238..48512e8 100644
>> --- a/doc/guix.texi
>> +++ b/doc/guix.texi
>> @@ -11676,6 +11676,11 @@ Please avoid marketing phrases such as ``world-leading'',
>>  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.
>> +Please avoid giving introductions to generic and repetive concepts
>                                                         ^
> I am not an English native speaker but ispell thinks this should be
> 'repetitive'.  In that case it may be better to just say
> 'generic concepts' since the concepts themselves are not repetitive
> only their explanations are repeated often?  I do not have a strong
> opinion though.

Thanks for finding the mistake. Yes, it should probably be reworded,
this was just what I wanted to get out. I will apply what you suggested
and send an updated patch in the next days.

>> which
>> +can can be found at external resources, such as ``tiling window manager''.
>> +Rather than giving an introduction to a topic in what should be a short
>> +description, think about its unique features.  If there are features which
>> +need explanation, keep it short and simple.
>>  
>>  @cindex Texinfo markup, in package descriptions
>>  Descriptions can include Texinfo markup, which is useful to introduce
>> -- 
>> 2.9.3

-- 
ng0
For non-prism friendly talk find me on http://www.psyced.org