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

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

[ng0]

[-- Attachment #1: Type: text/plain, Size: 700 bytes --]

I have seen too many descriptions which felt like they want to give an
introductions class to generic terms which are explain in external
resources.
A description should not be too repetive. As a system distribution, we will
have more than one tiling window manager. If you describe a tiling
window manager, point out and maybe short and simple explain its unique
features rather than giving the nth explanation of what a tiling window
manager is.
I want this to be included so that the *contributing* section which
points to this section in the documentation maybe points out to more
people that we do not need this.

If you have corrections or improvements let me know so that we can work
it out.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-The-description-should-not-be-used-as-an-introdu.patch --]
[-- Type: text/x-patch, Size: 1424 bytes --]

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 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


[-- Attachment #3: Type: text/plain, Size: 70 bytes --]


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

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

[Lukas Gradl]

[-- Attachment #1: Type: text/plain, Size: 1908 bytes --]

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.

> 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 818 bytes --]

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

[ng0]

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