From mboxrd@z Thu Jan 1 00:00:00 1970 From: George Clemmer Subject: bug#31786: 'pre-inst-env guix --version' is not updated by new commits" Date: Sat, 16 Jun 2018 12:06:33 -0400 Message-ID: <87k1qyaf7a.fsf@gmail.com> References: <87r2lddwyg.fsf@gmail.com> <87k1r4p2ca.fsf@gnu.org> <87k1r3271g.fsf@gmail.com> <87d0wvoicy.fsf@gnu.org> <87o9gf5x0t.fsf@gmail.com> <87wov3npl2.fsf@gnu.org> <20180614013938.GD29167@jasmine.lan> <87d0wttn0v.fsf@gmail.com> <87k1r1z5o0.fsf@gnu.org> <8736xnj22c.fsf@gmail.com> <20180615203018.clbx3kqjqfzcyink@abyayala> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:41058) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fUDjF-0005lg-39 for bug-guix@gnu.org; Sat, 16 Jun 2018 12:07:06 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fUDjB-00053n-Ti for bug-guix@gnu.org; Sat, 16 Jun 2018 12:07:05 -0400 Received: from debbugs.gnu.org ([208.118.235.43]:43965) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fUDjB-00053j-PY for bug-guix@gnu.org; Sat, 16 Jun 2018 12:07:01 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fUDjB-0005iO-IR for bug-guix@gnu.org; Sat, 16 Jun 2018 12:07:01 -0400 Sender: "Debbugs-submit" Resent-Message-ID: In-reply-to: <20180615203018.clbx3kqjqfzcyink@abyayala> List-Id: Bug reports for GNU Guix List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guix-bounces+gcggb-bug-guix=m.gmane.org@gnu.org Sender: "bug-Guix" To: Nils Gillmann Cc: =?UTF-8?Q?Cl=C3=A9ment?= Lassieur , 31786@debbugs.gnu.org Hi Nils, Nils Gillmann writes: [...] > Long text short nonsense: you end up with lots of work and long books if you > do it right. It should be done this way. Maybe if not directly applied we > could collect the proposals somewhere in the repository? I've recently > started to strip out a whole chapter with repetive installation instructions > in GNUnet. A while back I would've argued for keeping it, that we really > need to cover and guide every case. > Some projects have written "An introduction to..." books to lead up to > the manual. > In my opinion access to knowledge should be easy and without much 'rough > edges' to get it. > Do we keep it selfcontained? Reference other books? A middle path? It's > difficult to get it right if you don't have the time to think about this > as a fulltime job. [...] > > Do we really have to assume that everyone has the same skilset who wants > to get involved? Not about this topic, but in general? I think the assumption > that we share the same knowledge is difficult. Part of the excercise is to > reach out, actively, in person. Another part is to try and do it in text (be > it on a website or a (new) chapter in a manual). [...] > Counter-proposal: What about additional man-pages? man has enough sections > to provide well written, to the point, collection of notes for such day-to-day > usage. I'm not against your proposal, just another suggestion in context of > what I've written above. I think the Guix strategy, AIUI, of putting 99.9% of the doc effort into a single doc via Texinfo is very efficient. INFO and HTML reach the two extreme user types: hackers that use INFO and people use that google. Partitioning the problem into sub-parts is tempting. But it increases the risk of a sub-part drifting out of date at which point it is better to not have had the sub-part ;-) The Guix "mico-man-page" effectively eliminates a sub-part. Hackers can use INFO and people who google don't use man, so I think the micro-man approach is fine. I think the most promising and productive way for Guix to improve the end-user-friendliness of the doc is to use end-user "support incidents" to drive doc additions. At the end of an incident the user question is fresh in your mind, you have information that you know could have been helpful to at least one user, and you capture the support effort into something longer lasting. - George