From mboxrd@z Thu Jan 1 00:00:00 1970 From: ng0 Subject: [PATCH] doc: The description should not be used as an introduction to generics. Date: Fri, 26 Aug 2016 11:43:08 +0000 Message-ID: <874m67oiwj.fsf@we.make.ritual.n0.is> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:39231) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bdHCj-0006Es-31 for guix-devel@gnu.org; Fri, 26 Aug 2016 09:29:54 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bdHCh-0006pR-Rr for guix-devel@gnu.org; Fri, 26 Aug 2016 09:29:53 -0400 Received: from mithlond.libertad.in-berlin.de ([2001:67c:1400:2490::1]:35438 helo=beleriand.n0.is) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bdHCh-0006ot-EB for guix-devel@gnu.org; Fri, 26 Aug 2016 09:29:51 -0400 Received: by beleriand.n0.is (OpenSMTPD) with ESMTPSA id 1f7b2949 TLS version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO for ; Fri, 26 Aug 2016 11:43:09 +0000 (UTC) List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: guix-devel@gnu.org --=-=-= Content-Type: text/plain 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. --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0001-doc-The-description-should-not-be-used-as-an-introdu.patch >From e399e9a982e8a14e4e7f66d5318d3cf7919a81fb Mon Sep 17 00:00:00 2001 From: ng0 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 --=-=-= Content-Type: text/plain -- ng0 For non-prism friendly talk find me on http://www.psyced.org --=-=-=--