From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nils Gillmann Subject: bug#31786: 'pre-inst-env guix --version' is not updated by new commits" Date: Fri, 15 Jun 2018 20:30:18 +0000 Message-ID: <20180615203018.clbx3kqjqfzcyink@abyayala> 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> 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]:32989) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fTvME-0002rn-He for bug-guix@gnu.org; Fri, 15 Jun 2018 16:30:08 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fTvMA-0004Ka-6w for bug-guix@gnu.org; Fri, 15 Jun 2018 16:30:06 -0400 Received: from debbugs.gnu.org ([208.118.235.43]:42796) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fTvMA-0004KW-2P for bug-guix@gnu.org; Fri, 15 Jun 2018 16:30:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fTvM9-00020x-QD for bug-guix@gnu.org; Fri, 15 Jun 2018 16:30:01 -0400 Sender: "Debbugs-submit" Resent-Message-ID: Content-Disposition: inline In-Reply-To: <8736xnj22c.fsf@gmail.com> 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: George Clemmer Cc: =?UTF-8?Q?Cl=C3=A9ment?= Lassieur , 31786@debbugs.gnu.org George Clemmer transcribed 3.9K bytes: > > Ludovic Courtès writes: > > > Hi George, > > > > George Clemmer skribis: > > > >> Leo Famulari writes: > >> > >>> On Wed, Jun 13, 2018 at 08:54:49AM +0200, Ludovic Courtès wrote: > >>>> The other aspect, from a maintenance and readability viewpoint, is that > >>>> we could quickly add up lots of explanations that we’ll have to keep > >>>> up-to-date and that may make more important information harder to find. > >>> > >>> Yeah, I'm worried about this too. It's tough to strike the correct > >>> balance. > >> > >> IMO Guix is great for hackers, maintainers and sysops. The doc is > >> appropriate for such users, well done, spare, and already voluminous. > >> > >> This footnote suggestion, and others rejected in the past, are motivated > >> by my assumption that you will want to make Guix attractive to less > >> sophisticated users. > >> > >> Maybe my assumption is wrong? Maybe you want only "elite" users? > > > > No, definitely not; I’m sorry if this is the impression this gave. > > > > Like I wrote, my main concern is about keeping the documentation focused > > and maintainable. Sometimes we have to document things that are > > technically outside of Guix because there’s no real canonical > > documentation and because users would be impaired without it—I’m > > thinking for instance of bits in the “Preparing for Installation” > > section. > > > > In this case, we’d be documenting something that’s both outside of Guix > > and not vital for routine usage, and that’s mostly covered by the > > Autoconf manual. Hence my reluctance. > > > > I hope that makes sense. > > Hi Ludo’, > > I see the situation this way: > > The current doc reflects the needs and sensibilities of the hackers, > maintainers, and sysops that have built Guix. These "elite" users have > different needs and judge what is important quite differently from end > users. This guarantees that the current doc is inadequate for end users. > So, if, as you say, you want to make Guix accessible to end users, you > need to make changes in the doc. The questions: How? What? I understand where you are coming from, and I understand the trouble Ludovic (probably) has to find the right balance of content. Before I comment more below: I'm trying to adjust to a wide range of people with the least possible knowledge too in the new GNUnet documentation. Some documentations I looked at had this introductionary style for elements when they were first used. Texinfo has this element which seems to be less used because it renders terrible (or did not try with custom output definitions so far). It's sort of a box element. It would be good to extend this, at least that's my current idea, to eventually contribute to Texinfo when I have a better view on what we want. 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. > May I suggest ... > > a) Adopt a less defensive posture when responding to user questions, > comments, and bug reports. > > b) Be pro-active about capturing support resolutions in the doc. > > This thread presents a nice example of what I am talking about. To > recap: > > I said: I use 'pre-inst-env guix' this way and this is a bug. > > You said: Developers expect this, so it's not a bug. > > A less defensive response: Hmm, You are using 'pre-inst-env guix' in a > way we didn't anticipate. What are the benefits of using it this way? I > see how this is a bug for your use case. > > We discussed a workaround. I suggested adding it to the doc. > > You said: I’m not comfortable documenting this because it’s nothing > specific to Guix. > > I said: I urge you to reconsider. > > You said: This part of the manual targets developers... they know where > to look things up. [The more we write the more we have to maintain.] 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). > And Clément Lassieur added: > > > But non-hacker users can use Guix pull! Running Guix before it is > > installed (with pre-inst-env) is described in the manual as a "Hacker > > trick". > > > Guix pull is well documented, and should be usable for non-elite users. > > OK, but I'm non-elite and I have used Guix for 2+ years. I have tried > both. I prefer pre-inst-env. I expect others will too. The fact is that > pre-inst-env does not correctly report the version after 'git pull; > make'. How can you know that this won't be a problem for other users? > It only takes 4 lines to explain this and provide a workaround, e.g., > > Proposed (revised) footnote: > > (3) The Guix version in the Guix build is set by './bootstrap'. Thus, > the version reported by './pre-inst-env guix --version' is not updated > by subsequent 'git pull; make' steps. To update the version (and rebuild > everything), use 'git clean -dfx; ./bootstrap; ./configure; make'. > > - George 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.