From mboxrd@z Thu Jan 1 00:00:00 1970 From: Esteban Enrique Subject: Re: Some things to be aware of for docs Date: Mon, 15 Feb 2016 17:51:27 -0500 Message-ID: <56C2566F.209@gmail.com> References: <56C2281B.90104@gmail.com> <20160215220044.GB22646@jasmine> Mime-Version: 1.0 Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:53814) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVRzO-00047E-4G for help-guix@gnu.org; Mon, 15 Feb 2016 17:51:31 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aVRzN-00082O-2J for help-guix@gnu.org; Mon, 15 Feb 2016 17:51:30 -0500 Received: from mail-qg0-x231.google.com ([2607:f8b0:400d:c04::231]:32912) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVRzM-00082J-UJ for help-guix@gnu.org; Mon, 15 Feb 2016 17:51:29 -0500 Received: by mail-qg0-x231.google.com with SMTP id b35so120736558qge.0 for ; Mon, 15 Feb 2016 14:51:28 -0800 (PST) In-Reply-To: <20160215220044.GB22646@jasmine> 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 On 02/15/2016 05:00 PM, Leo Famulari wrote: > 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? Okay, so this is what RMS means when he encourages writing/editing documentation for the GNU project as a primary way to help these days. There exists documentation but it is poorly written for the aspiring beginner. The whole documentation situation is very bad on so many programs, it is not just you guys. I think it might stem from the fact that the developers of programs are so knowledgeable about their program that it is difficult to write in a way that welcomes new users rather than scare them away. For example, I have been learning emacs lately and the documentation there is top notch, very clearly written, for example. So yes, I agree with your disdain for the Arch way of creating documentation for 3rd party programs. I have always found their information helpful, and I frequently visit their site because it is so well documented. I have never written documentation or even edited or proofread or suggested anything, so this is something I would be willing to get practiced at and help doing for GuixSD. Also, as a part of the GNU project, I agree that our community should work on GNU documentation rather than create our own. > 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 Sure. In 7.1.4, probably in the beginning, 'guix pull,' as that is the advice I got from the IRC channel (which is great and very active! > 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! Yes, I have been frequenting #guix for a while now and it sure is helpful.