From mboxrd@z Thu Jan 1 00:00:00 1970 From: Leo Famulari Subject: Re: Some things to be aware of for docs Date: Mon, 15 Feb 2016 17:00:44 -0500 Message-ID: <20160215220044.GB22646@jasmine> References: <56C2281B.90104@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:40174) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVRCD-0004XC-4o for help-guix@gnu.org; Mon, 15 Feb 2016 17:00:42 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aVRC9-0004py-TX for help-guix@gnu.org; Mon, 15 Feb 2016 17:00:41 -0500 Received: from out2-smtp.messagingengine.com ([66.111.4.26]:60890) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVRC9-0004pu-Q6 for help-guix@gnu.org; Mon, 15 Feb 2016 17:00:37 -0500 Content-Disposition: inline In-Reply-To: <56C2281B.90104@gmail.com> List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: Esteban Enrique Cc: help-guix@gnu.org On Mon, Feb 15, 2016 at 02:33:47PM -0500, Esteban Enrique wrote: > I am a relative newcomer to GNU/Linux (4 years around) and I have been > wanting to use GuixSD for the past weeks but I have been having trouble. I > think this is due to unclear documents for beginners (like myself). Thanks for trying, and I'm sorry it hasn't worked yet! > > First, formatting the drive. I have some experience with Arch Linux, so I > had a general sense of how to use fdisk. However, for the vast majority of > those who don't know about this, there could be a link or a self-contained > explanation that goes through the process of formatting the disk. Personally, I feel a tension between improving the fdisk manual so that beginners can use it and just giving step-by-step instructions in our manual. I really don't like Arch's approach of working around poor upstream manuals by giving step-by-step instructions in their wiki, because it only helps Arch users [0]. If the fdisk manual is insufficient, we should help them improve it. On the other hand, in the meantime, *our* potential users are struggling to get started. I _do_ think it's valuable to provide instructions on using 3rd party software when it relates to quirks in our use of said software. For example, I wrote a section in our manual about using QEMU with our `guix system vm-image` command. What do people think? > > Next, (I think this has been in the works, but I am not sure) there needs to > be a reminder to run the command 'guix pull' before installation to avoid > any problems. The current version of the manual does mention this at certain points. Can you look at it and tell us where it's missing so we can add it? I know this is important to new users. FYI, you can build HTML pages of the current version of the manual from a git checkout like this: $ make doc/guix.html > > Finally, there could be a quick note which explains the slow download and > installation from hydra. This is really a temporary situation that should start to improve in the coming weeks. Perhaps we should add a note to the #guix banner. > > Overall, the documentation needs work, and I have yet to successfully > install GuixSD. I will be trying again soon and reporting problems /from an > experienced beginner's perspective/. This will hopefully make the project > more beginner friendly. (Note I do not use the term user-friendly (I hate > the term), because it does not need to be user-friendly, just welcoming to > those that are willing to take the time to learn what is up). Some of us are willing to spend *a lot* of time helping individual users get started. Please bug us on #guix or the help-guix mailing list with your specific problems :) We want to know your problems so we can improve the manual! > > There are more things that need help, but those are the ones I saw lacking > most. How often are the docs updated by the way? Constantly, but the web-based version is not. I just opened a bug about this. [0] I know that in practice users of other distros refer to the Arch wiki.