From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id UD0PHecZ2WHkwwAAgWs5BA (envelope-from ) for ; Sat, 08 Jan 2022 05:58:15 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id UHmyFecZ2WGHHgEAG6o9tA (envelope-from ) for ; Sat, 08 Jan 2022 05:58:15 +0100 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 838EA31362 for ; Sat, 8 Jan 2022 05:58:14 +0100 (CET) Received: from localhost ([::1]:42812 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n63nx-0003B5-N1 for larch@yhetil.org; Fri, 07 Jan 2022 23:58:13 -0500 Received: from eggs.gnu.org ([209.51.188.92]:47060) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n63id-0002wV-KE for guix-devel@gnu.org; Fri, 07 Jan 2022 23:52:43 -0500 Received: from sender4-op-o14.zoho.com ([136.143.188.14]:17476) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n63ia-00085X-2J for guix-devel@gnu.org; Fri, 07 Jan 2022 23:52:43 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1641617535; cv=none; d=zohomail.com; s=zohoarc; b=AZHPnDo+RZqZaLgKfLY/MPuHiqnhCAE8f/rxUWvlb/hmxjcQ8ntlsBuP0TyThFgS7xKsPgWpcBCjcAXhyTVS9BiUFF0p8jLlXa63ykWvxm17S3gDadM86b2BTyRmCWiDE7bld0Ioq0u3MOZ52or2qRV20w5axE5jqFGEWSYQX+Y= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1641617535; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:MIME-Version:Message-ID:Subject:To; bh=w1z3FUMSc7AuvF7QUXtfdXo0o6nxQBVY0L11Q+366ps=; b=buG2gEPfWsyLHcFITTmyexjQbZbaAcmtAaRUbOXMobSP4vhEJ72oXmgTSHKEHDAFmmt4evjFv8il5b2hhChaWflr2H8MBmOd5TrmBMvQItXx9vta3FFKjK9tuDE1BPWiKvTsGJtKpA+tyOo6ge4Fhl4jSyhgBqWwXaydzf7Fr58= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=excalamus.com; spf=pass smtp.mailfrom=matt@excalamus.com; dmarc=pass header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1641617535; s=zmail; d=excalamus.com; i=matt@excalamus.com; h=Date:From:To:Cc:Message-ID:In-Reply-To:Subject:MIME-Version:Content-Type:Content-Transfer-Encoding; bh=w1z3FUMSc7AuvF7QUXtfdXo0o6nxQBVY0L11Q+366ps=; b=fz3TBFvwiRHEfHVx+Tay+eALUW/uFD0eB9zVommqA0mfo//YbOGrkIukUT70ic+i XA7a7bmCIVzaTy4tF5BG9/1QMsYpREzDAeaP4JR8QZOzq2L4HOSVmxSjvNVHBrTKsKQ Nmhhae2ZMun82U7uamOcdi7KA9eHSRr98J4+eE9g= Received: from mail.zoho.com by mx.zohomail.com with SMTP id 1641617534531444.3877272488712; Fri, 7 Jan 2022 20:52:14 -0800 (PST) Date: Fri, 07 Jan 2022 23:52:14 -0500 From: Matt To: "jgart" Message-ID: <17e3807ae22.f1a020781024687.6953504682822686403@excalamus.com> In-Reply-To: Subject: Re: Guix Documentation Meetup MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 7bit Importance: Medium User-Agent: Zoho Mail X-Mailer: Zoho Mail Received-SPF: pass client-ip=136.143.188.14; envelope-from=matt@excalamus.com; helo=sender4-op-o14.zoho.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 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_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Mailman-Approved-At: Fri, 07 Jan 2022 23:58:02 -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: , 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=2; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1641617894; 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:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=w1z3FUMSc7AuvF7QUXtfdXo0o6nxQBVY0L11Q+366ps=; b=MhuZsaG3DbdiAA5RuJFIafoy8CgiwM+DTDeiMIzyQ0INa6BwDrZfsz29cWKpYHf1dZ5DKF 5/avjUgRGJ70cY5mRo97SEbt3Jkd98Ro/FYrokOAWAN0YJiULFAD0rRfIxEfAdzmuDgx7f APtJQkAnIPyXPzfWfEtfO5CXeOkgd+xsPnh3Gx7EocdphNpwqopex72s8zU+bDw62tUZXK AGaZ2lNWdn3gv4zcNpFIm0FQ8BzcGE600MkYlnfENfR9r0cxpM8nF1fwKT+jk4/q9xT+9w dFw/BjqNanK1ltfcs4C5nnBBJeZRpX0t4VJLHccgZDh/16OdLmsswMadjvRI9A== ARC-Seal: i=2; s=key1; d=yhetil.org; t=1641617894; a=rsa-sha256; cv=fail; b=TYa3Zm4jQjCYRrVy9agFkTUWZyueTIHa2iEgR1Wj6k4F+guYqdES/ZQfVKtxVIyr3DXjcG CvT8f/DcTbU5hSsNgmBKKV8IHiH93pxaU5+XBRXFhufZZpMj8+QRtuLdoaM84DpJ/vu+zh pvSwhj8ZOjJflxRyIGyZ8UaMN8FXverPQojGaHOsq7jDtp/VonQnp6RcCJnBbdfcfigbUW mH0SLbu1yc5Mx8xfNuWKFPwaZNucG3t2NIVx6x/9LiiJEI1U5GHW3FzP19+iCX2cJxqSAj PVzMW69AriXtIhjieHuBYM7ue0yK0IfdbBz1qmttJ4rerxE4Ul9R0nrbW43c0w== ARC-Authentication-Results: i=2; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=excalamus.com header.s=zmail header.b=fz3TBFvw; arc=reject ("signature check failed: fail, {[1] = sig:zohomail.com:reject}"); dmarc=none; 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: -1.09 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=excalamus.com header.s=zmail header.b=fz3TBFvw; arc=reject ("signature check failed: fail, {[1] = sig:zohomail.com:reject}"); dmarc=none; 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: 838EA31362 X-Spam-Score: -1.09 X-Migadu-Scanner: scn1.migadu.com X-TUID: p16OCka6Vvz4 I want to be a part of this. I feel like I've been rubbing two sticks together while it seems some people out there have Zippo lighters. A real-time conversation, some paired programming, or simply looking over the shoulder of someone who knows what they're doing would go a long way. I have been trying to learn and share by way of case studies: www.excalamus.com. My hope is that these could one day be adapted for the manual, or at least prep me for making meaningful contributions to the official documentation. I have several more studies that are unpublished. I share many of the same challenges others have experienced, certainly with Guile. These are things I'm interested in helping with: * defining terms A glossary, improved indexing (which is there), and more references (also present), are things I want to help with. For example, I've spent the past few days' free time trying to understand how to install an old version of ungoogled-chromium, required for Jitsi. To do this required 1) knowing what a profile is and 2) knowing the syntax of "sourcing". First, a profile is mentioned in passing several times in the manual as a directory. Yet, the guix package --profile option requires a *file* be specified. (yes, a directory is a file, but guix complains if you pass a directory). So, is a profile a file or a directory? After much poking around, I found that the file specified by the --profile option is a symlink. This symlink points to another symlink (specifying the generation?), which in turn appears to point to the directory of packages . So, a profile *is* a directory, but, depending on how you look at it, it may be a file. Second, to activate the profile requires "sourcing" $GUIX_PROFILE/etc/profile (again, is a profile a file or a directory?). Some parts of the documentation give this as: GUIX_PROFILE="$HOME/.guix-profile" . "$GUIX_PROFILE/etc/profile" Nevermind having to look up what was meant by "sourcing", I did that. But it turns out that there are two syntaxes for it: the one above and the more clear `source "$GUIX_PROFILE/etc/profile"`. Of course, with my luck, that wasn't made clear with the resources I found. It took me far too long to see how what I found on the open web corresponded to the manual. * meaning/consequences/significance Knowing words without understanding the consequences of their meaning is just memorizing jargon. A profile is a directory? So what? Is that significant or just trivia? I still don't know. Sometimes I think I'm reading about the Turbo Encabulator (https://www.youtube.com/watch?v=Ac7G7xOG2Ag) * context/workflows I want to help show what it means for Guix to be imperative and declarative. Each has a different workflow, it seems, and the manual mixes those together. The context isn't always clear. Guix is flexible. It can be complicated, but isn't by necessity. I've been able to get by for nearly a year doing, more or less, guix pull, guix package -u, and occasionally guix system reconfigure (with a few guix installs thrown in :) Almost all the complex stuff has been from my choice to learn and do more. The simple daily workflows aren't apparent to me from the documentation. I don't need to code a config or define packages or set up channels or profiles or do any of that unless I want to? It took a bit of reading for me to realize, that's it? I think there's a big focus on what can be done with Guix and not much said about the boring routine stuff. As a new user (even as a somewhat less new user), that's what I need first: I need security that my system will work, not crash or destroy my data and not consume my life *unless I choose for it to*. Isn't that really what Guix has to offer? Show me. * navigation/discoverablity Guix is described as "the Emacs of distros". To me Emacs, besides embodying freedom, means self-documenting. I wouldn't be a professional programmer without Emacs. It nurtures me by answering questions, giving examples, and scaffolding learning. Emacs expands the zone of proximal development (https://en.wikipedia.org/wiki/Zone_of_proximal_development) and ensures I can achieve what I couldn't before. Guix is poised to do the same. However, the documentation and my difficulty navigating it is a huge problem for me. Others have touched on it when talking about Guile. - Is this symbol from Guile or Guix? - What does it do? - How is it used? - How many steps are required for someone to answer these questions? (answer: not one like, C-h f. Instead, it might be days searching the mailing list, getting familiar with IRC, and being lucky with timing and and experimenting) - Geiser seems great. How the f*** does it help me answer these questions? Wait, what problem am I trying to solve again? I love the info system. Google has nothing on the info reader. Yet even the info system's ability to overcome the documentation trilemma is strained. The documentation trilemma is: Intelligible, comprehensive, and discoverable: Pick two. I feel Guix does pretty well on being comprehensive. And, despite some rough spots, it's largely intelligible. Guix fails for me on discoverablity. Can I quickly find the answer to my question *and know that I've found it?* That's why I think defining terms, focusing on their significance, and providing context through workflows can help. Discoverablity is also a technical problem. I want a C-h f for Guix. That's something I think Guix and it's community is well positioned to solve, what with all these reproducible environments, Emacs users, and what not. I'd love to help that come to fruition. I can write and publish all day on my blog, but if it's not discoverable and, more importantly, not correct, it's not helping anyone. I, and people like me, need help from experts. That's why I'm so excited about this meet up. I know I can string some words together enough to be understandable. But is what I'm saying helpful? One final question: How might announcements of the "Guix Documentation Meetup" (and "Guix Packaging Meetup)" be made more prominent? I check the mailing list from time to time, but missed the announcements because they were buried. Maybe meetings could be announced on info-guix? If they become regular, maybe put them on https://guix.gnu.org/en/contribute/? FWIW, I'm willing to be present so that a documentation meetup could run monthly. I'm an FSF member and could use the FSF Jitsi service if I needed to host it. I've not used Big Blue Button before. Sometimes I wonder why I'm choosing to struggle to learn Guix. The reason I choose to persevere is that Guix could be like Emacs, software for a lifetime. That's something I'm willing to invest in.