From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id eDOcJr09t2FF0AAAgWs5BA (envelope-from ) for ; Mon, 13 Dec 2021 13:34:05 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id +F5PIr09t2FkZgAAB5/wlQ (envelope-from ) for ; Mon, 13 Dec 2021 12:34:05 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 4103034FDB for ; Mon, 13 Dec 2021 13:34:05 +0100 (CET) Received: from localhost ([::1]:41778 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mwkWq-0007yZ-Ec for larch@yhetil.org; Mon, 13 Dec 2021 07:34:04 -0500 Received: from eggs.gnu.org ([209.51.188.92]:35470) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mwkWd-0007vy-Lu for guix-devel@gnu.org; Mon, 13 Dec 2021 07:33:51 -0500 Received: from [2001:41d0:2:863f::] (port=29230 helo=out1.migadu.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mwkWU-0003zi-8u for guix-devel@gnu.org; Mon, 13 Dec 2021 07:33:51 -0500 Date: Mon, 13 Dec 2021 19:33:29 +0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nonconstructivism.com; s=key1; t=1639398817; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=NJ+5jOKFJ/+pVcfInC6L+/skZQHucIVzLnyjTCTHQcA=; b=GTgZGHFv2HqYteBcdWpYywp1fap2bjVx6tP6CH366gWC2zWl621B5TNN+2bkIQ97gvC6ks X4Y7bALYzE9BJVgXn05IJFjVk/0Y1PIu+GKVLmJYOpzO1Fs8KeaWUhtgdjRyHlXl2fPbIn 4a5VDwEWFaBdBKxk6tJfoHDmYFIs3ps= Message-Id: <87fsqwd6qu.fsf@nonconstructivism.com> To: zimoun Cc: jgart , Guix Devel Subject: Re: Guix Documentation Meetup Gcc: nnimap+imap.migadu.de:sent.2021 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. From: Blake Shaw MIME-Version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Host-Lookup-Failed: Reverse DNS lookup failed for 2001:41d0:2:863f:: (failed) Received-SPF: pass client-ip=2001:41d0:2:863f::; envelope-from=blake@nonconstructivism.com; helo=out1.migadu.com X-Spam_score_int: -12 X-Spam_score: -1.3 X-Spam_bar: - X-Spam_report: (-1.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RDNS_NONE=0.793, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: guix-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: "Guix-devel" X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1639398845; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=NJ+5jOKFJ/+pVcfInC6L+/skZQHucIVzLnyjTCTHQcA=; b=I4D0nEt8690ov8/FFbGTCp97SHFtHyiSllzew8eOllCuft6G7MPezZj0zl8U6Fi8Hq+uKx 0umhHrXngJ2X9l1eG0I7wx4LR34YS8wQvrNe0tnY033WZfO+acK+MLrGLKN0sCfITa7vGe rLNdV+DJXYHfS6XB4zIe/eJnNb72cNujuAYTjFKgZ/FQqsffoiImYbaHt2Po8ftMEwe41O ziBkv3jHY4ES4uJY+3fRTLwvf1fVUu4s152beLEMxYyhCvxebRhgfcBodCarYOAb2hScCO 6g9vhHEz8mDA2LHFyrGbMLbBmbM5nhXZpBocLgODL7hWnP3lx4AXemfd2qVo/g== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1639398845; a=rsa-sha256; cv=none; b=LEJDrntKMcZ+E+5Fznvj0W88tS3himAyP6s0zUf3sKKpLm3tB8BdCnl/Uy+6leJBAfiuO4 20Ic3dmMJgCiYbBvp87DleUwEWd3N4J6BzYn4LO1cVgNxUkvpguWfcL+aXoWS5jIupLYHU bZ686htYipekCI/Ryz8KlzevpFgApuBQ7I79fS/T1Y/e3BD6DbJ6dOJC1MdWv3MdeVZmPP 4G5PsXoMQNSC00gjaWkLCkzTIT2gObjDc4QZ4NWUFNYAHUOKvRWPlmNriW/d9T7D4gafjZ YHAhvHpZ6ErIFGB4mg4NAZQt77AXeYuckctfODM+gU93VrNbRx/Kzb6f4tnptQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=nonconstructivism.com header.s=key1 header.b=GTgZGHFv; dmarc=pass (policy=quarantine) header.from=nonconstructivism.com; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -3.16 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=nonconstructivism.com header.s=key1 header.b=GTgZGHFv; dmarc=pass (policy=quarantine) header.from=nonconstructivism.com; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 4103034FDB X-Spam-Score: -3.16 X-Migadu-Scanner: scn1.migadu.com X-TUID: R3/t5W+PkxWF zimoun writes: Hi Simon, thanks for the input, > Hi, > > On Sat, 11 Dec 2021 at 05:40, Blake Shaw > 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 # > 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: > >> 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”