Ludovic Courtès <ludo@gnu.org> writes:
Toggle quote (38 lines)
> 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?
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.]
And Clément Lassieur <clement@lassieur.org> added:
Toggle quote (6 lines)
> 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
