From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nils Gillmann Subject: Re: Some things to be aware of for docs Date: Tue, 16 Feb 2016 00:54:34 +0100 Message-ID: <87si0ta5s5.fsf@grrlz.net> References: <56C2281B.90104@gmail.com> <20160215220044.GB22646@jasmine> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:39788) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVSyW-00029I-DN for help-guix@gnu.org; Mon, 15 Feb 2016 18:54:41 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aVSyT-0005K5-75 for help-guix@gnu.org; Mon, 15 Feb 2016 18:54:40 -0500 Received: from latitanza.investici.org ([82.94.249.234]:52975) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVSyS-0005Js-UK for help-guix@gnu.org; Mon, 15 Feb 2016 18:54:37 -0500 In-Reply-To: <20160215220044.GB22646@jasmine> (Leo Famulari's message of "Mon, 15 Feb 2016 17:00:44 -0500") 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: Leo Famulari Cc: help-guix@gnu.org Leo Famulari writes: > On Mon, Feb 15, 2016 at 02:33:47PM -0500, Esteban Enrique wrote: >> >> 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? > --snip-- > > [0] I know that in practice users of other distros refer to the Arch > wiki. I would refer to gentoo wiki section handbook, subsection formating the disks (or smth like that) for this as it's very understandable for inexperienced user in my opinion. But that's just me, where I already had 14+ years of experience when I read it 1 or 2 years ago. Gentoo documentation is overall very good (the wiki section) and gets the balance right. I think something similar to this is a nice approach. Documentation is something most people don't do good enough, and as long as the upstream docs aren't good, it would be good to have something in one place to refer to. -- ng