Re: Guix Documentation Meetup

[zimoun]

Hi,

On Sat, 11 Dec 2021 at 05:40, Blake Shaw <blake@nonconstructivism.com> wrote:

> --
> tldr: is there also room to discuss contributing -- and possibly doing a
> sizeable makeover to -- the *Guile* documentation? If so, I could give a
> short 5 - 10 minutes presentation of what I think should be done (and
> would volunteer to do).
> --

Cool!

Minor comments trying to feed this worth proposal.


> I don't know if this is the correct forum for it, but I personally think
> the biggest documentation obstacle in Guix at the moment isn't so much
> in Guix, but instead in Guile. I found Guix via SICP & Racket about a
> year ago, and I remained a happy Racket hacker until a couple months ago
> when I decided to devote my free time to learning Guile in hopes of
> graduating to a Guix sensei one day.

I agree that the learning path in Guile land is not always smooth.
However, I do not think mastering Guile and/or its specificity is a
requirement to be a “Guix sensei”.  Obviously, better Guile
documentation improves the ecosystem, then it is an overall better. :-)


> While I've come to love Guile, compared to my experience with Racket its
> been quite burdensome for me to get in the hang of, something I attribute
> primarily to the structure of the docs, and not due to it being in any
> way more difficult than Racket. While with Racket I was writing
> useful programs in the standard #lang within my first week, with Guile
> I often find that what should be almost trivial winds up with a lot of
> time lost just trying to navigate and understand the docs. When I do
> figure things out, it turns out to be no more difficult than the equivalent
> in Racket, but a lack of consistency in the path that leads there in the
> docs cause hangups, which has made trivial scripts that should take an hour
> become weekend projects.

Well, I am not convinced it is because the structure of the docs.
Instead, I think it is because it is missing docs. :-)

If we compare apple to apple, here are the entry points:

    https://docs.racket-lang.org/
    https://www.gnu.org/software/guile/learn/

and so the Guile manual

    https://www.gnu.org/software/guile/manual/guile.html

is a reference manual, which correspond to, mainly

    https://docs.racket-lang.org/reference/

and also,

    https://docs.racket-lang.org/guide/

I am not convinced you started Racket by these ones. ;-)

Indeed, one document on the Guile side vs two documents on Racket side;
the Guile manual could be split, I do not know if the core issue here.
Instead, IMHO, what is missing are all the others. :-) For instance,

    https://htdp.org/

which is a really smooth introduction.  Somehow, it appears to me
that it is missing an introduction, a similar document as,

     https://www.gnu.org/software/emacs/manual/html_mono/eintr.html


> I know this isn't the Guile list, but when I've written on this topic in
> the IRC I've had no response, which make me think docs could be a
> bit of a bikeshedding topic in the community. But as Guile is
> fundamental to Guix and theres a lot of crossover btwn the communities,
> it seems like this could be a good time to raise these suggestions.

I agree.  For what it is worth, I tried once to quickly explain monad,
with the aim of “Store Monad“ in mind,

    https://guix.gnu.org/manual/devel/en/guix.html#The-Store-Monad

After several discussions with strong Guix hackers, it appears to me
that they missed the general concept of monad, at least it was vague.
Therefore, I tried to write a simple explanation,

    https://simon.tournier.info/posts/2021-02-03-monad.html

Bah, the other part has never seen the light, another story. :-)  Long
time ago, Pierre wrote down a quick introduction to Scheme, which ended
into the Cookbook,

    https://guix.gnu.org/cookbook/en/guix-cookbook.html#Scheme-tutorials

>From my point of view, the missing documentation is the one between
newcomer and Reference manual.  For instance, setup a Guix/Guile
environment is not straightforward; Geiser helps, but even after some
time, I am often still fighting against it, and I do not know what
exists outside the Emacs world.


On the Guile land, one feature which really annoys me is the poor
discoverability from REPL; for an instance,

--8<---------------cut here---------------start------------->8---
$ guix repl
scheme@(guix-user)> ,a fold-packages
scheme@(guix-user)> ,use(gnu packages)
scheme@(guix-user)> ,a fold-packages
(gnu packages): fold-packages   #<procedure fold-packages (proc init #:optional 
modules #:key select?)>
scheme@(guix-user)> ,d fold-packages
Call (PROC PACKAGE RESULT) for each available package defined in one of
MODULES that matches SELECT?, using INIT as the initial value of RESULT.  It
is guaranteed to never traverse the same package twice.
--8<---------------cut here---------------end--------------->8---

well, IPython, GHCi, UTop (to name some I use) provide a complete
different experience.  Well, maybe resuming this discussion [1] is
worth.

1: <https://yhetil.org/guix/86d00evkmr.fsf@gmail.com/>


> I've jotted down some notes on several concrete examples of where the docs
> diverge from stylistic consistency, as well as some light analysis as to
> why such seemingly small inconsistencies can lead to such hangups in the 
> learning
> process. If folks would be interested in me presenting a short 5-10min
> presentation of these notes, I'd be happy to share.

I would be interested to listen your ideas, here, there or overthere. :-)


Cheers,
simon