From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id gOoHAUMCtGGeUAAAgWs5BA (envelope-from ) for ; Sat, 11 Dec 2021 02:43:31 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id 6FpXOEICtGHbCgAAB5/wlQ (envelope-from ) for ; Sat, 11 Dec 2021 01:43:30 +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 994D86AB2 for ; Sat, 11 Dec 2021 02:43:30 +0100 (CET) Received: from localhost ([::1]:60390 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mvrQ9-0003tD-NT for larch@yhetil.org; Fri, 10 Dec 2021 20:43:29 -0500 Received: from eggs.gnu.org ([209.51.188.92]:39724) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mvrP5-0003t2-RM for guix-devel@gnu.org; Fri, 10 Dec 2021 20:42:23 -0500 Received: from out0.migadu.com ([94.23.1.103]:30894) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mvrOy-0004R1-5d for guix-devel@gnu.org; Fri, 10 Dec 2021 20:42:20 -0500 Date: Sat, 11 Dec 2021 08:42:10 +0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nonconstructivism.com; s=key1; t=1639186933; 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=M7DOiPKQxZxJEpWSwagNkNxy0r6wES8Ree1Vtq+HUZA=; b=L2cjIZZdjRdZWmBDbmZGY1Ddw4UnwcRCTyjWBe2rhg2w2/STAsxIWW1oRRdeljFkrA4wni M1zvaHUZghc9O9A3P9fvqCNNqKTqKrjvI1suyzxWC6bnf3Y3zKVHSnBHlQMM76qS/949s3 6d/41ipUHOl4zoa9dOe+pkEbFAaXcPs= Message-Id: <87sfuz3ojx.fsf@nonconstructivism.com> To: Ryan Prior 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 Received-SPF: pass client-ip=94.23.1.103; envelope-from=blake@nonconstructivism.com; helo=out0.migadu.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 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, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham 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=1639187010; 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=M7DOiPKQxZxJEpWSwagNkNxy0r6wES8Ree1Vtq+HUZA=; b=WctIbacJaETcWizc06R8XG9yVdoNybdgXdjbm01KEaAj/aSKm2YqXOk/YEaYFTx0aKajzm HBleCiIEZPwhpZXaIAKCXrqndnV9RWWk5aO6rTWrLpyLmA7SGUT3DV0V0hXzaoKzTVeVP1 DmMFQZzRdTQvGBZoE0p6PQvUP5SpG+cia70OH/iYF8Df3wHQPvr2a55C985FxF8np7qN0E ft/2SXlIJZTyqKXJXtWI0aDvAvu/CKO248RjRghPqK9xsr5iE/TM4gl/Lss3a9uNvT04xa uiyyBxP4HBlFwc6GJlkHQwiRa9GFX4W67a/2m+fo9JIUa7O6FoJgjV6afm+R4Q== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1639187010; a=rsa-sha256; cv=none; b=nRePy0AkiYjL/GljU/4EfTs380AyQ4u+HMUMpZFMW671ackgHZNlkpnWtueCzUvpoqUJUP kBarU3QxlmpXwhQYEKmK3G6LYVJ1P/f/QdS0fJxVT/21whC/m6RDZNJIxw54DoxN+tjI47 pI+pZ48jdwhO2j/LT7dHzxLMoO9AXOwAGZNqw9NlKHrdpKpczCaVvGb1uHkdWbkuabBzoh JF4TT7Mx2hZ7V6MZYXpuz0Ibg1Tp9+u5gkl4rlXPwGnJBNcKNAd0vmXIOOMIDE5Y4dAxmS 3JUIjB5OM7rg4psmtTfjTZ24dIg+4fQZF6Ak4p9EWKOAA+xE6DQKs8EhmBh5YQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=nonconstructivism.com header.s=key1 header.b=L2cjIZZd; 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.26 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=nonconstructivism.com header.s=key1 header.b=L2cjIZZd; 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: 994D86AB2 X-Spam-Score: -3.26 X-Migadu-Scanner: scn1.migadu.com X-TUID: GcEjZDeLL+xP Ryan Prior writes: > Absolutely. The Guile docs are unusable and make Guile a pain to work > with. I say this as an experienced lisp & scheme user with decades of > experience now in elisp, racket, and clojure. oh good, I'm glad to hear that I'm not alone! to be honest I don't think its *so* bad, but it certainly demands a the user of suffers a bit, which makes Guix in general a more difficult sell. And Guile is a truly impressive programming language; its docs are just in need of some remodeling I think. > I've found the Guile IRC channel to be polite and encouraging, but > also very self-satisfied, which makes it hard to feel heard as a Guile > hacker who's struggling. I hesitate to tackle any kind of nontrivial I first checked it out when I began learning about guix, and it seemed quite friendly. but unfortunately since I started studying Guile I haven't had any of my questions there responded to. hopefully all is ok. > problem with Guile because I have no confidence I will find tools that > save me time; I'm proficient with a half dozen other languages, > including multiple lisps, which provide much better support. So even > though I really want to learn Guile,because of Guix, Shepherd and > other cool software written in it, I'm no more likely to choose Guile > for a software project today than I was 3 years ago when I just > started learning it. As long as it doesn't stall out into bikeshedding and the community is supportive I'm dedicated to this project of working on Guile's docs while I become acquainted with its depths. As a media artist theres really a lot it offers. But like you say, it can suck up time with little return; trying to figure out certain basic things in Guile has made C feel like Python at times. Luckily, the C interface is decently documented. > > When I talk to experienced hackers in the Guile community I get the > sense they've just accepted that yeah, the only way to get anywhere is > to cold memorize the most popular ~80 SRFIs or implement everything > you need yourself. One person I talked to was like "oh yeah Guile's > great, you just have to implement your own standard library like I > did." I'd be interested to hear any anecdotes regarding whether restructuring the docs was attempted in the past, and what problems it incurred. Considering my background in academia, writing is second nature, and this has been the only thing in Guix that has appeared to me as a serious pain point, so if I'm the only one who doesn't find writing docs insufferable, I'm happy to take on that task for the time being. But again, it depends on whether the community will grant me their confidence. > I'd love to hear your talk, if you're up to present at the Guix meetup > I'll definitely come and listen. I'm also happy to do what I can to > help drive Guile adoption, create a great learning experience around > it, and finally start to build the language community that Guile is > lacking. Awesome! Me too! It's seriously an incredible language -- it's just lacking a consistent, ergonomic presentation atm. But even without that, it's the fastest-booting lisp I've tried, and already thats enough to keep me from crawling back to Racket (which might boot fast now with CS, but I haven't checked in lately) As it currently stands, its better to ditch the docs and just browse the code base. And while for some that might be like reading email, for the vast majority thats demanding some serious overhead from users who are likely to pick up Guile for their personal, off-hours, creative work. It won't be a talk, just a 5-10min presentation of some notes where I'll try to provide a light analysis of a few problems, along with how I would go about fixing them, and then if all agree I'll get to work on it. Thanks for the encouragement! ez, b -- “In girum imus nocte et consumimur igni”