From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id 0HYSLvAFt2HKIgAAgWs5BA (envelope-from ) for ; Mon, 13 Dec 2021 09:36:00 +0100 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id yhXhKfAFt2FFIQAA1q6Kng (envelope-from ) for ; Mon, 13 Dec 2021 08:36:00 +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 4B6CD12EC9 for ; Mon, 13 Dec 2021 09:36:00 +0100 (CET) Received: from localhost ([::1]:37654 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mwgoR-0003lq-D1 for larch@yhetil.org; Mon, 13 Dec 2021 03:35:59 -0500 Received: from eggs.gnu.org ([209.51.188.92]:49228) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mwgo2-0003ja-O9 for guix-devel@gnu.org; Mon, 13 Dec 2021 03:35:34 -0500 Received: from [2a00:1450:4864:20::42a] (port=33763 helo=mail-wr1-x42a.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mwgnz-0005AZ-Rg for guix-devel@gnu.org; Mon, 13 Dec 2021 03:35:34 -0500 Received: by mail-wr1-x42a.google.com with SMTP id d24so25761335wra.0 for ; Mon, 13 Dec 2021 00:35:31 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:in-reply-to:references:date:message-id :mime-version:content-transfer-encoding; bh=PDrByfEUyZRu6FpW6NkLbB89AdCzQ4JqlagpdqMB3bs=; b=GtCIwJr8iZv4B2HJCFPWqbuxkEU2wd9ChcI5n+O8eSL1wNQtmwrIhk2TDcPaYtEe/O a3HPbTU6OH55XuXWSH3J2Aa3ZL+CTjXXkjn0Ubcd6z+ecUy1ugTC25yR/M6V53ISnwk3 YUEGUyQZ+8XmixWZg5KsuDws3JZADvBh6dsEzfsQw2TusbKp8QW44POMjxHVOsGXs7Yy QOexW5Vb/mZZHinJu/s4fTMWeavmp/hlu0bYj9JSVO9R1iD+v+8aXTDl16MiEZRtOpDM 27TCFBoKR1GCH6Gg3pC11A2yYt2uEE+R2jeevPGgUVYLxmjVsNkmorrR5qR0dxwmTv0e Li/A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:in-reply-to:references:date :message-id:mime-version:content-transfer-encoding; bh=PDrByfEUyZRu6FpW6NkLbB89AdCzQ4JqlagpdqMB3bs=; b=miareKv2G+J6UuMzI1GLslPoqqXeB/n3DwtwxTd5IYoeW9B0jFnc9vQppyDfnfDYxS OjXa1HJbCgotslzt8h40zv/eGgf9CVrvmyodTkgkvkI7fW9hBOVvZTOCt49Ae7+sxGih NAt68f+WgtuIh9k3IxVk2lnuxecIETLvbZ3n1utNKwgeO/z1NEiy2DVNzvboklg/R8yO XKUpFFNttfPacG6Q51zlMvTRqRVGfiwOqKqbcMDGAYIzArdnTeNLsDo2+t2Jc4RbJwK6 iK2enKv4IrfUUxU4qyLISr3NJr9ZQy5EEe5Pw4faLnOrcP/WokQ/ZGT4O6ZyF6zTft5y qd3A== X-Gm-Message-State: AOAM530tPIIKzowNCcoo9wckbbubwWPYl7olRJ/BZDO124dvGqdslsVL KIkvb2M3nLvpMXTpFr17pf1iCasKDE0= X-Google-Smtp-Source: ABdhPJwOEpTIschkBhaMCi82WkPf2PNWTxm9GbtfADeBbtJkae9QF2nGu1BqSRpDQpwP+neCmGMYfg== X-Received: by 2002:adf:9cc4:: with SMTP id h4mr15371276wre.644.1639384529190; Mon, 13 Dec 2021 00:35:29 -0800 (PST) Received: from lili ([2a01:e0a:59b:9120:65d2:2476:f637:db1e]) by smtp.gmail.com with ESMTPSA id v9sm7797582wrb.107.2021.12.13.00.35.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 13 Dec 2021 00:35:28 -0800 (PST) From: zimoun To: Blake Shaw , jgart Subject: Re: Guix Documentation Meetup In-Reply-To: <87y24s13u8.fsf@nonconstructivism.com> References: <87y24s13u8.fsf@nonconstructivism.com> Date: Mon, 13 Dec 2021 09:29:34 +0100 Message-ID: <86lf0osya9.fsf@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Host-Lookup-Failed: Reverse DNS lookup failed for 2a00:1450:4864:20::42a (failed) Received-SPF: pass client-ip=2a00:1450:4864:20::42a; envelope-from=zimon.toutoune@gmail.com; helo=mail-wr1-x42a.google.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, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, 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: , Cc: Guix Devel Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: "Guix-devel" X-Migadu-Flow: FLOW_IN X-Migadu-Spam-Score: -4.00 Authentication-Results: aspmx1.migadu.com; none X-Migadu-Queue-Id: 4B6CD12EC9 X-Spam-Score: -4.00 X-Migadu-Scanner: scn1.migadu.com X-TUID: 3D11jkDeozAF Hi, On Sat, 11 Dec 2021 at 05:40, Blake Shaw wrot= e: > -- > 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 =E2=80=9CGuix sensei=E2=80=9D. 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 equivale= nt > 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 ho= ur > 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 =E2=80=9CStore Monad=E2=80=9C 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 # 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: > 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