From mboxrd@z Thu Jan 1 00:00:00 1970 From: Alex Sassmannshausen Subject: Re: FAQ Date: Sat, 16 Jul 2016 20:15:43 +0200 Message-ID: <877fclbga8.fsf@gmail.com> References: <20160716143632.GA14742@solar> <20160716171834.GA15167@solar> Reply-To: alex.sassmannshausen@gmail.com Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:53753) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bOU7w-0001Qj-2m for help-guix@gnu.org; Sat, 16 Jul 2016 14:15:49 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bOU7v-0000NL-33 for help-guix@gnu.org; Sat, 16 Jul 2016 14:15:48 -0400 Received: from mail-wm0-x233.google.com ([2a00:1450:400c:c09::233]:34980) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bOU7u-0000NG-Rl for help-guix@gnu.org; Sat, 16 Jul 2016 14:15:47 -0400 Received: by mail-wm0-x233.google.com with SMTP id f65so59917273wmi.0 for ; Sat, 16 Jul 2016 11:15:46 -0700 (PDT) In-reply-to: <20160716171834.GA15167@solar> 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" To: Andreas Enge Cc: myglc2 , help-guix@gnu.org Hello, Andreas Enge writes: > On Sat, Jul 16, 2016 at 01:02:33PM -0400, myglc2 wrote: >> Vincent Legoll writes: >> > OK, I'll try to create a FAQ section in the official doc then... >> Great idea! > > Hm, lest I be misunderstood: The aim is that reading the manual should > be sufficient. If there is a frequently asked question, it should not > be added to an FAQ section, but the section of the documentation where > the question should be answered should be updated. > > My reply was half meant as a joke. And half seriously: As a little joke > we could add an FAQ with only one question: "Where is the FAQ?" and the > answer "There is none, if you find the documentation is lacking, please > submit a patch to improve this manual." or the like. hmm… I sympathise strongly with the notion of contralising documentation as much as possible. It strikes me that an FAQ is meant to do something else from a manual though: whereas a (reference) manual is meant to be as comprehensive and detailed as possible, an FAQ can provide high-level, short responses to common questions. Because Guix is relatively unique in its approach to package management, it may well be worth trying to address some high level questions in an FAQ, which in turn might link to the relevant sections of the manual for more detail. I don't know if this is the right way to go, but I'd be interested in seeing a (patch) proposal for such a type of FAQ as an appendix to the manual if this was what was indeed intended. WDYT? Alex