[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] doc: The description should not be used as an introduction t
From: |
ng0 |
Subject: |
Re: [PATCH] doc: The description should not be used as an introduction to generics. |
Date: |
Sun, 28 Aug 2016 21:26:15 +0000 |
Lukas Gradl <address@hidden> writes:
> [ Unknown signature status ]
> ng0 <address@hidden> writes:
>
>> From e399e9a982e8a14e4e7f66d5318d3cf7919a81fb Mon Sep 17 00:00:00 2001
>> From: ng0 <address@hidden>
>> 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