From mboxrd@z Thu Jan 1 00:00:00 1970 From: myglc2 Subject: Re: [PATCH] Quick-start guide Date: Sun, 12 Jun 2016 11:14:34 -0400 Message-ID: <86r3c2a17p.fsf@gmail.com> References: <8760tjkft8.fsf@gnu.org> <20160611174955.GA9544@jasmine> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:43660) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bC77f-0008Ff-DT for guix-devel@gnu.org; Sun, 12 Jun 2016 11:16:24 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bC77b-0000vX-7N for guix-devel@gnu.org; Sun, 12 Jun 2016 11:16:22 -0400 Received: from plane.gmane.org ([80.91.229.3]:57256) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bC77b-0000v2-0M for guix-devel@gnu.org; Sun, 12 Jun 2016 11:16:19 -0400 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1bC77V-0000qd-M4 for guix-devel@gnu.org; Sun, 12 Jun 2016 17:16:13 +0200 Received: from c-73-167-118-254.hsd1.ma.comcast.net ([73.167.118.254]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Sun, 12 Jun 2016 17:16:13 +0200 Received: from myglc2 by c-73-167-118-254.hsd1.ma.comcast.net with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Sun, 12 Jun 2016 17:16:13 +0200 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 Leo Famulari writes: > On Sat, Jun 11, 2016 at 06:43:21AM -0700, yoosty@gmail.com wrote: >> Upon further reflection.. The Guix manual might not be an appropriate place >> for such a guide. If the Guix manual isn't a good place for such a set of >> instructions, do you have any suggestions for a location (blog, etc)? I think your first intuition was correct: this information should be added to the manual. > There is this useful wiki managed by Raymond Nicholson: > https://gitlab.com/rain1/guix-wiki/wikis/home > > Although, I'd like to echo Ludovic's question, and also say that the > goal of the manual is to be completely sufficient for first-timers and > experienced users alike. This is the correct goal, but the manual as it stands is problematic for first-time users for reasons such as: it's overwhelmingly copious; information is "shredded" into different sections; the is confusing terminology; finding one's way around is difficult; there is virtually no guidance of what to read first or how to proceed. I see this patch as an attempt to address some of these difficulties. > I find the phenomenon of 3rd party wikis giving instructions on how to > use some piece of software to be a dismaying "antipattern". And, the > situation only gets worse as people send documentation to the 3rd > party wiki instead of to the software project in questoin. To avoid the "antipattern" we need to make Guix documentation more friendly for first-time users and be more _receptive_ to comments and patches from first-time users. I suggest we add a new "Getting Started" section between "Introduction" and "Installation". "Getting Started" should initially include a discussion of how to decide whether to install Guix or GuixSD and quick-start sections for each. This patch should be used as the "GuixSD quick-start" section.