guix-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Guix Documentation Meetup


From: Blake Shaw
Subject: Re: Guix Documentation Meetup
Date: Mon, 13 Dec 2021 19:33:29 +0700

zimoun <zimon.toutoune@gmail.com> writes:

Hi Simon, thanks for the input,
> 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. :-)

I mostly agree, and I used Guix for probably half a year before recently
deciding to dive into Guile seriously. But I still won't be able to,
say, write a `guix import` for a different package manager without
needing to spend ample time consulting the docs, bumping up against
confusions, etc. I want to get to the point that I'm able to take
on such matters with confidence, and so learning Guile seems important.   

>
>> 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'm covering all this in a presentation I'll be putting together over
the coming weeks, including some visualization of the structure that I
think is helpful. I'd argue that `Hello Guix`, `Hello Scheme`,
`Programming in Scheme` and `Programming in C` serve a similar function
to `Quick`, `Continue` and `More` in the Racket docs.

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

I started with the Racket Guide! or really, with SICP and `#lang
sicp`, doing little bits of the Racket Guide along the way and that got
me interested in racket more generally.

But probably more importantly, I think like many programmers I
started writing little projects in Racket and read the docs along the
way. And thats where my analysis focuses: the documents should, and can,
be easier to navigate, allowing one to get in-and-out as needed, but
currently there are many related functions buried in disparate areas
usually without examples. Why FTW and POSIX in disparate parts of the
manual, things its obviously desirable to use in tandem? Why are there
multiple ways to do IO without a disclaimer as to which is prefered? If
there are 30 documented SRFIs, and most have only 1 or two sentences
written for most, but some contain a treasure trove of knowledge, many 
people will move on after linking into one or two SRFI entries and
forgoe the rest, and won't realize there are tranducers in guile.

All of this adds up to a fair amount of overhead imo, and I'm planning
to put together a report covering a structural analysis of it before the
end of the month.

> 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 haven't read htdp, but its always at the top of recommendations
regarding Scheme literature (or PL in general). I mean, Scheme in
general has better book-length literature than possibly any other
language! Dybvig's The Scheme Programming Language has been the most
helpful, but still, it doesn't tell me anything about GOOPs, Guile's
compiler infrastructure, Tree-IL, CPS soup, etc. 

but I guess my point it, those are canonical works by some of our finest
wizards. If someone can bring that degree of pedagogical pedigree to the
Guix ecosystem we will certainly be blessed. But I think what I can
personally offer is to work on refactoring what currently exists.
>> 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

nice, I look forward to checking this out! yet another monad tutorial is
always due for those of us who never ventured far down that path.
>
> 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.
>
Yeah, I agree. We need a "More Perfect Setup" for hacking on Guix! In
particular, I think it would be helpful to add a section showing how to
jump to definitions emacs style; thats probably been the most helpful
tool for learning, personally.

> On the Guile land, one feature which really annoys me is the poor
> discoverability from REPL; for an instance,
>
> $ 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.
oh interesting, I didn't know that it sometimes will fail to find a
package. in general, I'm a big fan of definitions in the repl. the less
I have to look away from my text editor, the better. this is certainly
smthng that could be improved. 
>
> 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
>
>
thanks for the feedback! looking forward to keeping it going.

blake
-- 
“In girum imus nocte et consumimur igni”



reply via email to

[Prev in Thread] Current Thread [Next in Thread]