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 19:07:23 -0500 Message-ID: <20160216000723.GA27625@jasmine> References: <56C2281B.90104@gmail.com> <20160215220044.GB22646@jasmine> <87si0ta5s5.fsf@grrlz.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:42068) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVTAm-0003ZZ-Rt for help-guix@gnu.org; Mon, 15 Feb 2016 19:07:21 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aVTAj-0008Fi-K6 for help-guix@gnu.org; Mon, 15 Feb 2016 19:07:20 -0500 Received: from out2-smtp.messagingengine.com ([66.111.4.26]:57070) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVTAj-0008FR-BN for help-guix@gnu.org; Mon, 15 Feb 2016 19:07:17 -0500 Content-Disposition: inline In-Reply-To: <87si0ta5s5.fsf@grrlz.net> 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: Nils Gillmann Cc: help-guix@gnu.org On Tue, Feb 16, 2016 at 12:54:34AM +0100, Nils Gillmann wrote: > 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. I suggest that if the docs of fdisk (for example) are insufficient, why not improve them directly, rather than creating some distro-specific list of instructions that will need to be manually kept in sync with updates to fdisk? Re-documenting fdisk in a distro's documentation is the wrong approach, in my opinion.