From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id PwNeBid6wWGatwAAgWs5BA (envelope-from ) for ; Tue, 21 Dec 2021 07:54: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 mp1 with LMTPS id IHRHASd6wWGGRgAAbx9fmQ (envelope-from ) for ; Tue, 21 Dec 2021 06:54:31 +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 A39442AA4B for ; Tue, 21 Dec 2021 07:54:30 +0100 (CET) Received: from localhost ([::1]:46110 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mzZ2b-0004JY-HZ for larch@yhetil.org; Tue, 21 Dec 2021 01:54:29 -0500 Received: from eggs.gnu.org ([209.51.188.92]:55796) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mzYqA-0007uF-Ip for guix-devel@gnu.org; Tue, 21 Dec 2021 01:41:38 -0500 Received: from mx1.riseup.net ([198.252.153.129]:55598) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mzYq5-00081U-US for guix-devel@gnu.org; Tue, 21 Dec 2021 01:41:36 -0500 Received: from fews1.riseup.net (fews1-pn.riseup.net [10.0.1.83]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "mail.riseup.net", Issuer "R3" (not verified)) by mx1.riseup.net (Postfix) with ESMTPS id 4JJ6LL56cqzDq9w; Mon, 20 Dec 2021 22:41:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=riseup.net; s=squak; t=1640068890; bh=e6gXZqN87uqT+6jC1llqY5lUAVoGo8Gwuiozu1xMh2A=; h=Subject:From:To:Cc:Date:In-Reply-To:References:From; b=ArwY9TERxVQnvHm/UBjy0+BGYfa2yTIqh/tdwlIVFMeFQ7kKtCgB/UUgOKGCZGgyH gK2a4hM+MOaXo2SivsaY5hEWwEB+vSJYXTpnKzK4gh7GQ5D0mfe6mkNE3r3fbnOqzu yO3TCCwpGtoPnDJHQcfyECylDB9zWCN5LjcwXRT8= X-Riseup-User-ID: 49755B00AE092BA237A95C11505C193BA490F281007FA36FAE87F00AA60B8E89 Received: from [127.0.0.1] (localhost [127.0.0.1]) by fews1.riseup.net (Postfix) with ESMTPSA id 4JJ6LJ6JRfz5vYh; Mon, 20 Dec 2021 22:41:28 -0800 (PST) Message-ID: Subject: Re: Guix Documentation Meetup From: adriano To: Blake Shaw , jgart Date: Tue, 21 Dec 2021 07:41:21 +0100 In-Reply-To: <87y24s13u8.fsf@nonconstructivism.com> References: <87y24s13u8.fsf@nonconstructivism.com> Content-Type: text/plain; charset="UTF-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Received-SPF: pass client-ip=198.252.153.129; envelope-from=randomlooser@riseup.net; helo=mx1.riseup.net 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_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-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: , Cc: Guix Devel Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: "Guix-devel" X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1640069670; 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: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=Tg9RD/8HB5wX2scTmAY83alhE49MRKRjCqU6W6VaAkg=; b=lWJuY1M25MD0WNPlaXJ58J52ASuLO2gd5oa+eMvXVM+u/EQ2YHBHsc0QHLFMegKUHErz/p bO3gc/pY0NfkcWPd4/azlIzy5N8va8/fi/+wbWkJqfzLn8/z9fYc/UGC88tsrR7xJ/D5oq LUyyL88PqEOTlN5+KMpExCgBUMnSntuFRwUEvoGjt3linA9tk3/wfkJYnRChmS1xHIqMYu WMqKK6JloGo5rYu9TP8jLqgGN7IoXOHkjAJIIXFCQO1Wp+zZOB4eYdwav4/wXkt7G05z9J FkmCswKt9wL2/YL9TmP+VpR/4P0UgAz43YXPsT2P0kX8ykV1UGN/7fFdSAVIZQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1640069670; a=rsa-sha256; cv=none; b=ZvXDMgVuFpGVt+TOXNf+Y58gSrHc4nuYwwGWn4oy5L93Bo5Xs2BnCb0hjC/H8VLXirB4L1 Ws60GiFakzX6GrbXrVrBndrMhUPr9inhTgj7Pb0n/N5PPhX1WNRpuAl8u64ZlCGg+TsCEG i3IsxbtchbNU7+dY+3g/dk9o7YLFebf9LYx8g9NdzF1f1AnRMBieLcYisQgLd2+icny4s1 nj71dtCqU6NRZYfyWpaeouXgyeP/Dd5OTgthF9f8aHnUIk+Fe3HBLhxFugQvyqGFa9kuPF qAQAdqraklkiXggpxeSE1Uf3vrlI1b42RBgeDi1X6XvMks24F0vq7gHzhgscVg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=riseup.net header.s=squak header.b=ArwY9TER; dmarc=pass (policy=none) header.from=riseup.net; 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: -7.22 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=riseup.net header.s=squak header.b=ArwY9TER; dmarc=pass (policy=none) header.from=riseup.net; 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: A39442AA4B X-Spam-Score: -7.22 X-Migadu-Scanner: scn0.migadu.com X-TUID: +M9O/k5fXloP Il giorno sab, 11/12/2021 alle 05.40 +0700, Blake Shaw ha scritto: > > hiya guix, > > @cybersyn from IRC here, I recently contributed my first package, > [notcurses] > > -- > 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). > -- I'm reading this on december 21st I suppose the documentation meetup happened already and I don't know if you gave your illustration of your notes I, for one, would LOVE to hear it Yes the Guile experience is abysmal, awful, actively rejecting beginners/newcomers I've been wandering in the Guile manual, on and off, for years now and I still can't make any sense of it If I have a curiosity I still can't find my way around to such thing in the manual, most of my discoveries have been by pure chance Often, I try to re-read the same thing a few months later and I can't find it again Everytime I attempted something in Guile I've been frustrated I myself have done a so called vlog where I show how to read a file in Guile I also have a general view of packaging and distributing Guile packages that I gained by some very hard work that lasted a couple of years but I was discouraged in doing more videos Not only previous knowledge of the GNU system is a not declared hard requirement Often, previous knowledge of other things is required too For example the new exceptions system is obscure, you're required to know the one from Common Lisp in order to undertsand the one in Guile Or,as another example, I stumbled in an example made in python of a hashmap (similar to the ones very common in Clojure) and I got that Good luck with data structured in Scheme Or, the machinery for manipulating xml (and json ?) trees is discussed in academic (!!) papers that present the code in Haskell, so you need to learn Haskell in order to read that The curse of knowledge in the Guile world is tragic > I think I can personally offer a lot in terms of contributing to > documentation. While I don't serious experience w/technical writing, > prior to the pandemic I was doing my PhD in philosophy of > mathematics, > so I come from a cross-disciplinary background that involves the > often > difficult area of communicating new, formal ideas to previously > unexposed readers. I've also made a living as a new media artist > since > 2009, working mostly in C and C++ based frameworks, so I also have > some > knowledge of the difficulties "crafters" have when learning new > development systems. That's all good. I love that you noticed the problem and are offering a fresh perspective > 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.  Absolutely, yes > 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. Not only a Guix sensei but maybe a Guile sensei Why has Guile only Guix ? Why couldn't we have more nice things made in Guile ? > 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. > > 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. Oh I love this ! > 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. yes pleeeease !!! > Sorry for such a long-winded message! Personally, good documentation > is > absolutely essential, and I feel like I could give Guile's docs a > serious makeover while I'm still at the early stage of my plunge and > have a perspective on the psychology of not-understanding -- > something > that won't last long! Oh God, did you give this talk ? Is a recordng available ? If it's not, you should make a vlog ! Please ! > > ez, > blake >