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 qORYBvTYs2GfbwEAgWs5BA (envelope-from ) for ; Fri, 10 Dec 2021 23:47:16 +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 8HcYAvTYs2GdYwAA1q6Kng (envelope-from ) for ; Fri, 10 Dec 2021 22:47:16 +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 C1F4924958 for ; Fri, 10 Dec 2021 23:47:15 +0100 (CET) Received: from localhost ([::1]:33392 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mvofa-0008W9-OT for larch@yhetil.org; Fri, 10 Dec 2021 17:47:14 -0500 Received: from eggs.gnu.org ([209.51.188.92]:60164) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mvoZ1-0007Kh-5U for guix-devel@gnu.org; Fri, 10 Dec 2021 17:40:27 -0500 Received: from out1.migadu.com ([91.121.223.63]:36926) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mvoYy-000117-1X for guix-devel@gnu.org; Fri, 10 Dec 2021 17:40:26 -0500 Date: Sat, 11 Dec 2021 05:40:15 +0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nonconstructivism.com; s=key1; t=1639176018; 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=LtuTlAevnbE+nHzjaHxjfYz1F5nwJxRpY+C/W8gp938=; b=WcgRPmUW9JQWD2HuvEU1bGMdfyuC6oXZ6f32xvcZM7Ws4fLSPk52leQyF70DPZrYT7Yb6u oGEiV/78qmHQsIM/u4nxhmHLEZl6J6wdUjnU8gfe0xZ2YKT6bqtQjndE8aHfZO7yhh2gaa URG0nejLx+6DVwjkgfYqKHl+U50/To8= Message-Id: <87y24s13u8.fsf@nonconstructivism.com> To: jgart Cc: 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=91.121.223.63; envelope-from=blake@nonconstructivism.com; helo=out1.migadu.com X-Spam_score_int: -7 X-Spam_score: -0.8 X-Spam_bar: / X-Spam_report: (-0.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, PDS_TONAME_EQ_TOLOCAL_HDRS_LCASE=1.997, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-Mailman-Approved-At: Fri, 10 Dec 2021 17:47:05 -0500 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=1639176435; 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=LtuTlAevnbE+nHzjaHxjfYz1F5nwJxRpY+C/W8gp938=; b=UgrWyuw6EWqIKt2jlnG8PJIra0WnG4xD0VqcOG4fOkcqOlpvzDvIBwLLONaFdr5oM4sbMg dDqR0TeGiyqSP2daMH5jLT3dpGaxW7H4Gk8nfpE3IAUwN7BSZOsqiMOorlALEB7M3kKfvd I7Fe/yPSp+KOrBYXrx2nI+OcUodkG87MzQkO+r75lPd/njU6cOgNUlm6lKRJRok6HPUZM5 jV4TScvfFT4vLyNKAiOP8WJstxFoe+nxhGlZUELjnueX4RNuUtN/KBklaFUWLGOIkOunyW JaUEkuj8dVl/Vv40ehkfMdzQfjI3b7OFzPY3QEV/+ZZOFRh6yeRLK5Jvf06neg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1639176435; a=rsa-sha256; cv=none; b=uYfG9yNB4znizh5lkfFG9Zxt6TOZ48UFS50gHE6AQVSoPBh0uXvWM27ONHApYe7gONGQmG 00GVMC8Rr+PhlSnEWzf+vrOgsciQwZuBOODtoHjU9zOti8k6L7qPLnqSyRJrb/Bz63eHtI DXqGUT7pjljC4wCVY3K0p4LzYrzLn7kZE6kE0FYYlzTPJAB/MYxHax0NLI3P/8VoBozJqy jM3nIvLfwk6pXsH95xO3R4nYPbNuNbRvVTJbCyKWO+GM/iACT1TLBZ1u6i6v3cTVfaykvg H9UwpyC1jb8hgu8bxAbTOSYf2vA0AGqZLnXtkrkXHtdJzYHqe6S5OW4loAk+lA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=nonconstructivism.com header.s=key1 header.b=WcgRPmUW; 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=WcgRPmUW; 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: C1F4924958 X-Spam-Score: -3.26 X-Migadu-Scanner: scn1.migadu.com X-TUID: Ol/8krCTQJUl 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 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. 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. 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. 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. 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! ez, blake -- “In girum imus nocte et consumimur igni”