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

[George Clemmer]

Hi Nils,

Nils Gillmann <address@hidden> 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