From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id 0Fr1AiXDtmHvFAEAgWs5BA (envelope-from ) for ; Mon, 13 Dec 2021 04:51:01 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id WH5JOiTDtmEqYgAA1q6Kng (envelope-from ) for ; Mon, 13 Dec 2021 03:51: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 82D1E17EED for ; Mon, 13 Dec 2021 04:51:00 +0100 (CET) Received: from localhost ([::1]:60844 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mwcMd-0002dI-JL for larch@yhetil.org; Sun, 12 Dec 2021 22:50:59 -0500 Received: from eggs.gnu.org ([209.51.188.92]:40792) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mwcLv-0002d6-Lv for guix-devel@gnu.org; Sun, 12 Dec 2021 22:50:15 -0500 Received: from [2607:f8b0:4864:20::d35] (port=45685 helo=mail-io1-xd35.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mwcLm-0007PK-5Y for guix-devel@gnu.org; Sun, 12 Dec 2021 22:50:08 -0500 Received: by mail-io1-xd35.google.com with SMTP id q72so17036143iod.12 for ; Sun, 12 Dec 2021 19:50:04 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:message-id:references:date:in-reply-to :user-agent:mime-version; bh=sDbzZE+/Wb+0N5VIrXfhBGMQk0UaCJ68Bcaf/5Y8HlQ=; b=MNFzFcimCsy4ShA9A2f/WL1Ux7k0xH9timPhol3d+Bt9j1PpaK9um6YyVQqsqJn+UX zi6VSW8daUYpPbEbWGYrS6SXS14kdGHIjejuGJYSxByxeVmbQdj4W2zTBQVMlf4Hrcch Ho/W+P2/u8GeVPbAjZ8wa+Vz0mnTpCY+FupkczssO1SbXJxtoMCJW1RbaftjZBR3ny7C YSNh15bodPqGF6ItD5oQ1Z72UTHoVERq5j70WYM0bcReVXZVwfAtBXerlLJXKF0vGWFq PReF2Hj858meWLm/xesrMHTvkvmIA+ULVIdmXEdq1xBNsk2BsdgSJFgDbMiWTYWelESr nuQw== 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:message-id:references:date :in-reply-to:user-agent:mime-version; bh=sDbzZE+/Wb+0N5VIrXfhBGMQk0UaCJ68Bcaf/5Y8HlQ=; b=cxfoLC0wac6FtV1iyymFsyuZqQLVDk507HTdBmxYJI14LcNdLdP0fyjOhasdNp6bv8 qVGhrfWz05nUC3XNIcKnk7bm9YArb+Ec683xRy4Eqt63dk7E227xu86tuebuM/fkN+Sr IMREtYcf7bJ1pM5AhjZtaConxyh1veuuXq7kCpPTD34W3KubTXnuzPMfImVjqEA+O7sw y+zBU8zgyYUKAt48HfKQMi2TlxgEsW8wMiQ1Y4hY/18UjMSv/pQZ4kKa1nPKstX+uiu7 5fyJnp0Z3b2dq/hH5lsbaZmOiWVBx0YrZur/XRrJseMZx10S2yJLz7CNhVPtZi24C1Af 4e6Q== X-Gm-Message-State: AOAM5308q6dTIQp0+585+XFBMb1U+1jf0jbeTivVDZoI8ElkK0YGIh91 L9Ankb/49P32mIFAK2F5X3oARVpebwM= X-Google-Smtp-Source: ABdhPJy7oxfUJQdErxAasMHrzNsalfcUJ16umC/P/m7mOY1Ge6ik6vjPnIoufYhz18wLh1lr7DesMw== X-Received: by 2002:a5d:9844:: with SMTP id p4mr31970033ios.109.1639367403951; Sun, 12 Dec 2021 19:50:03 -0800 (PST) Received: from washu-v4 (172-221-246-205.res.spectrum.com. [172.221.246.205]) by smtp.gmail.com with ESMTPSA id 10sm7854257ilx.42.2021.12.12.19.50.02 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 12 Dec 2021 19:50:03 -0800 (PST) From: Katherine Cox-Buday To: Blake Shaw Subject: Re: Guix Documentation Meetup Message-ID: <87sfuxfyps.fsf@gmail.com> References: <87y24s13u8.fsf@nonconstructivism.com> <871r2jgeed.fsf@gmail.com> <87lf0q2m7n.fsf@nonconstructivism.com> Date: Sun, 12 Dec 2021 21:50:02 -0600 In-Reply-To: <87lf0q2m7n.fsf@nonconstructivism.com> (Blake Shaw's message of "Sun, 12 Dec 2021 16:42:36 +0700") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Host-Lookup-Failed: Reverse DNS lookup failed for 2607:f8b0:4864:20::d35 (failed) Received-SPF: pass client-ip=2607:f8b0:4864:20::d35; envelope-from=cox.katherine.e@gmail.com; helo=mail-io1-xd35.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 ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1639367460; 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:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=sDbzZE+/Wb+0N5VIrXfhBGMQk0UaCJ68Bcaf/5Y8HlQ=; b=qfOr0DFbuoFmg847GKKkkA13PPnIc/stYRv8VkFRmSjRz/57H5lqVFxxYINr82EXCcKJdN zOTVUCSwKm7K5/Ayoer//kT2EpOp37rtQfNX7O414f9BywdrddpA1AZuZrm8dUAeSB0n17 XVf+9Oomx2UzSqZKbRDX55qvLLdlrmRnOsecaqDpwGU6STCawiGxY12tWn3+/+iU/QweTK UxcsHUKuh2P0NExUuLl8Z1UwpgqeRvbfivjMPjvhSI3S8XLw4EhPdsEF450TAWnM6wPzF6 X72S2YRWDcqroyZmr3Zv/MAZgF9NGrqcuPrD7g9gms2OHee9CpSIFzt3rP2S8Q== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1639367460; a=rsa-sha256; cv=none; b=pps4UTLF1XepahpNg6HlbNS1v4WABAAg3ql6CD+n7Vha/RmYq8Kb7D6H+0xn3gCN8zeFKk gQ0VstPcSXM6FZCsH/b0dvhO7EL6XW8HuLSU7LPfNBnNwx93+Lr2P7HZKuZ+KFEmDiQczO XvHXDuEvk4smdlqCbAjcPe7QmxGWROwv5nmHVO4BD0h+mx1DMH6R6SsAatynme8jsHWe8O wRjWM48e1l1PqDzi1i6wgrPgyNLdcbbO/PDoSNEYV9iyVRnL2omA/OvVmPBQtCnU/QRgAa 2p8NhxYNMSVioQQBWEzJEObm8YBJkWfv4wUZTXjig6QY8nG0Uzdm102PqjapHg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=MNFzFcim; dmarc=pass (policy=none) header.from=gmail.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: -4.17 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=MNFzFcim; dmarc=pass (policy=none) header.from=gmail.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: 82D1E17EED X-Spam-Score: -4.17 X-Migadu-Scanner: scn1.migadu.com X-TUID: jk5NyDu9S/yE Blake Shaw writes: > I'd love to know where you found trouble so that I can take that into > consideration when developing a design strategy for the makeover. When reading this, please keep in mind that I have a lot of gratitude for the various maintainers of this software and its respective documentation. Communication is very difficult, and relaying my experience and opinions is meant to convey that experience, and not to criticize anyone's efforts. I think my frustration stems from the confluence of me not being familiar with scheme, how Guix writes scheme, how scheme the language and ecosystem work, the tools we have available to us, and then finally the documentation. Not being a schemer (yet?), I can't speak with much authority, aside from the fact that I've written code in many languages, and most of these pain points are well addressed in others. Usually, my frustrated workflow goes like this (warning: ignorance on display! :p): - Identify something in Guix I want to do - Open (or create) a file - Start geiser - Start writing Guile - Come upon a semantic structure I want to write, and realize I don't know the Guile way to do it. - In geiser, run =,a thing-i-want-to-look-for= (this is supposedly an apropos command that is supposed to search symbols for you). The command returns nothing. I realize I have to import the module implementing the thing I'm looking for first, thus defeating the purpose. - Before, I would then go here[1] and try and textually search for the symbol. I have recently discovered the emacs function: =helm-info-guile= which makes searching a bit faster. - Find that there are multiple, competing, modules which do the same thing in different ways. - Realize I don't know which one to use, or which one Guix would prefer. - Sometimes, realize that Guix has their own wrapper around one of the modules, and learn that something I thought was standard scheme is actually a Guix neologism. - Import one and try it. Maybe import another and try it. Lose track of why I've imported things as I'm trying them because the module names have no indication of what they implement. - Wish that Guix had a standard to prefix function calls with their module, as we do with =license:=. - Have no way of automatically and programatically cleaning up imports to work around this. - Forget what I was even trying to accomplish. Go to bed and try again tomorrow! Specific to Guile documentation, I guess if I boil the above down, it would be something like: Early in the documentation, directly address the intrinsic fragmentation of the scheme ecosystem, and how a new Guiler is meant to navigate that. Do so in terms that don't rely on experience with the Scheme ecosystem. The Guile reference manual has this[2] section which, to me, is a paragraph which touches on this, and then much later has a blurb[3] on what SRFI is. I had no idea what =ice-9= was, and the first mention[5] of it in the manual is one of its modules. To my knowledge, what =ice-9= is, or why it's called that, is never addressed. It appears[5] I am not the first to be confused by this. As a newcomer to Guile, and to scheme, I would expect Guile to give me its opinion of how to do things (i.e. which modules to prefer, what is considered "standard" in most schemes) until I've written enough Guile to form my own. As it's written, my impression is that the documentation relies on the reader knowing a lot about scheme coming in. I feel there just needs to be an easier gradient for people trying to use Guile as their first scheme. It is not specifically Guile's problem, but as a service to its developers, the meta-topic should be addressed so a new developer is not left confused. When we put a lot of work into something, it's really easy to fall in love with the idiosyncrasies of the thing, and to lose sight of what it's like to come into an ecosystem with no context. This can result in addressing things that feel important to us, the expert, but are really much further up the ladder of complexity. When writing a landing page for a language, I feel the following is important: *Don't overwhelm your newcomers.* Your landing page should have few links, and they should directly address high-level questions: - What am I looking at? - How is what I'm looking at organized? - What should people like me (e.g. non-programmers, programmers, schemers, people who don't speak English) be reading? - A link to a site which provides easy to use symbol lookup. The documentation can fan out in complexity from there, but the landing page must not be overwhelming. Anyway, those are my opinions :) [1] - https://www.gnu.org/software/guile/manual/guile.html [2] - https://www.gnu.org/software/guile/manual/guile.html#Guile-Scheme [3] - https://www.gnu.org/software/guile/manual/guile.html#SRFI-Support [4] - https://www.gnu.org/software/guile/manual/guile.html#ice_002d9-optargs [5] - https://lists.gnu.org/archive/html/guile-devel/2010-07/msg00045.html -- Katherine