bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[Nils Gillmann <ng0@n0.is>]

George Clemmer transcribed 3.9K bytes:
> 
> Ludovic Courtès <ludo@gnu.org> writes:
> 
> > Hi George,
> >
> > George Clemmer <myglc2@gmail.com> skribis:
> >
> >> Leo Famulari <leo@famulari.name> 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 <clement@lassieur.org> 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.