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 wMp5Dx7BuGG2XwEAgWs5BA (envelope-from ) for ; Tue, 14 Dec 2021 17:06:54 +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 IP9cCx7BuGEBKQAA1q6Kng (envelope-from ) for ; Tue, 14 Dec 2021 16:06:54 +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 D6B09D751 for ; Tue, 14 Dec 2021 17:06:53 +0100 (CET) Received: from localhost ([::1]:34356 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mxAKL-0002uu-1v for larch@yhetil.org; Tue, 14 Dec 2021 11:06:53 -0500 Received: from eggs.gnu.org ([209.51.188.92]:34640) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mxAFM-0007Nk-5G for guix-devel@gnu.org; Tue, 14 Dec 2021 11:01:44 -0500 Received: from [2607:f8b0:4864:20::f2d] (port=46880 helo=mail-qv1-xf2d.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mxAFF-0001iO-TW for guix-devel@gnu.org; Tue, 14 Dec 2021 11:01:43 -0500 Received: by mail-qv1-xf2d.google.com with SMTP id jo22so17600503qvb.13 for ; Tue, 14 Dec 2021 08:01:37 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=4vi5wMbfv1cyKJnEDCb4JTWOeTMNV7oNRjpMhQ4nAKo=; b=OvyXzkPgTTsmycRUdy6vF6Hma4ZucCSC68/KYQaKQx79zL/U84F+XgSoKWXtSFIi/5 U/be4gU5D7Ai7wCHhsTRSxasgI6Cmoa6ZARX/gK6roAoK/gJQPK8JJd+dyEMUAGTXKlD vmC7YVK+Azk2YkqjnKmNNQ99NrbIDo2fL8XZLJ3oBXWL6POUmUi0zwtE1R7+uYNfHBE6 i5+1Bf3Ds9HEVfI5VALe7TFTwaeXGDPBjXTephAwiL9pyli3OycD9KxaGYdPKU88Pzyr p039lhNWAj7GxXtUGc/no3hjTDj2FxAwWMfPIUyJGU6TPCxP9EirKgyCysEcN41rRjib npLA== 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:references:date:in-reply-to :message-id:user-agent:mime-version; bh=4vi5wMbfv1cyKJnEDCb4JTWOeTMNV7oNRjpMhQ4nAKo=; b=M5kSJrebxc5kem6nyfyP+mvsrcwKYfv7O9afSOJ9suDaje9G9/ONKaDvLZOScILfSF 8aLELznwc4i+B7EsjEyKVQTX9Yk7DPobEGXoTOz+KG3m1fDZPeomDoNANcmBwJ/A7PGj LKMCZsMt4gqkIgi29EzDt1jYarZk6NTYBcA6sinU7NSa5+w2XCeo+FMPbm1DV6IBJWtJ 0hrx9MfV20wrVC3q3g2rQHEhpZxcFHneEZJ/zUbGOWH2CGhYBTOH7RlCFzvpalmmvV3v Mh07vugClVAxXnbC8IiGX3FxdJMZc5y1HpdNFsnLL0Uhc4B0Qs1yGwYzSgy7Jurp2e5R cBZA== X-Gm-Message-State: AOAM533IAsAALjNMqWPHbp/jTvnldBOcKCqn2sR40JwiSm7iIz9A5VkS 8LGFtRed2bOlnWtn0XoaIB2IEPXAUPc= X-Google-Smtp-Source: ABdhPJzHOjz1T9qUZya5l+/dJHqZt7GAEJYIJrPsHoRZQqNUpeL0N2XeumhMdNbXRc1/I71WPgAizQ== X-Received: by 2002:a05:6214:1631:: with SMTP id e17mr6326831qvw.58.1639497696942; Tue, 14 Dec 2021 08:01:36 -0800 (PST) Received: from washu-v4 (172-221-246-205.res.spectrum.com. [172.221.246.205]) by smtp.gmail.com with ESMTPSA id r8sm232678qtw.35.2021.12.14.08.01.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 14 Dec 2021 08:01:36 -0800 (PST) From: Katherine Cox-Buday To: zimoun Subject: Re: Guix Documentation Meetup References: <87y24s13u8.fsf@nonconstructivism.com> <86lf0osya9.fsf@gmail.com> Date: Tue, 14 Dec 2021 10:01:34 -0600 In-Reply-To: <86lf0osya9.fsf@gmail.com> (zimoun's message of "Mon, 13 Dec 2021 09:29:34 +0100") Message-ID: <87ee6ffa5d.fsf@gmail.com> 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::f2d (failed) Received-SPF: pass client-ip=2607:f8b0:4864:20::f2d; envelope-from=cox.katherine.e@gmail.com; helo=mail-qv1-xf2d.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 , jgart 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=1639498014; 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=4vi5wMbfv1cyKJnEDCb4JTWOeTMNV7oNRjpMhQ4nAKo=; b=ewRdPV1FUnfYRRIIxFr99OBcKwkOeE3foDBF9Kqpzla7sk009rCDLjybVd8KXCpSyVJKEr TNBrzOhYFtDAAF5cfSitQjPCmlBqMzeSY76VgeQMP8IPAOwkFJzkHtJPQSPWmZKDkzHeRe zLmtDJLUGI53cyoXP/f8uUKLC6PkcXXeJ+vqaC4loJNqitCOk9LqYGGyKr40e/r7X+SZc1 +UIrT7N9E1XdeaR9YLzb5v4HV1ervjvWlz6dHNCC2sge3rnpGcw9gjaJ26sUFN7cOKnL7T D44Jqone1wNJerJPndXINHUERr2gJs5vuBE0fDE4ankVJtp88CVQDDiaDrxHrw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1639498014; a=rsa-sha256; cv=none; b=GuyWyyabGowVhauVkoDmqHl+eRq9mMFjWx6rnf3ysOhRHCSq8PYu9R9OmX+eaG95+zfUQW 2ujD5QQVyfK2r3hUZgiB3mO6UAlcYrwURwTOLuJzfLhGI/cQkcDVq3vX2KelbRrOtrXhzB fx8Ui0ojnJVw5JkLrXzIFFm4Jbk3R/2vUaG9DmtjRLrM6J9Ut0ITCYoWT6KMnCB8YMNDXs D3qBSNhFxq75Z/D5cp9OjrLq8yGVHm1rrNIOWSQnAjJYpN2dc4qClhPDmo6cWPZ9FFH3+v yLudJwJV8RzqiuwXUz7m9IbGegGsMOxqxqMQvBZse08ydWwQ8uRN9ALp9FUZhg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=OvyXzkPg; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=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.87 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=OvyXzkPg; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=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: D6B09D751 X-Spam-Score: -1.87 X-Migadu-Scanner: scn1.migadu.com X-TUID: 6O3JAFV1FtnK Here is some analysis on various popular languages' documentation landing pages. I did this on Sunday, but I held it back from my previous message because it was already quite long, and I was worried this would be seen as over-critical and maybe raise the ire of various language fans. But I think it might add to the conversation and help create better Guile documentation, so I'll risk it :) For context, the only language on this list I really know well is Go. Guile: ====== - Tutorial for extending a C program with Guile - The manual - Scheme Resources - "The Revised^6 Report on the Algorithmic Language Scheme" - "" but 7 - "" but 5 - (more links that IMO are only meaningful if you already know Scheme) Overall, I'm left feeling like I have a clear sense of direction because it's apparent to me that I should click through to the reference manual. Experience with the GNU ecosystem helps here. I am left wondering whether I should click on any of the other links, and what I might be missing by not doing so. But clicking through reveals lengthy documents that I don't know if I should read yet or not. Once I do click through to the manual, I am in a pretty familiar GNU document, and the other comments about this document become applicable. The one thing I would add here is that other languages have a separate symbol/library explorer with a few more bells and whistles to support jumping around. It would be nice if Guile not only curated opinions on which modules to use, but used a separate, more featureful site for that. Go (https://go.dev/doc/): ========================= - A blurb trying to sell Go - A link on how to install Go - Links to tutorials and opinions on how to write Go. - Links for very specific topics like editor plugins and fuzzing. Overall, this seems cluttered and disorganized. For some reason there are several links to tutorials on very specific topics before there is a link to look at the packages in the standard library. These tutorials seem to be interspersed with more fundamental, important, beginner topics, and I'm not sure why. The link to look at the documentation for the standard library -- something a developer will be working with a lot -- is titled "Package Documentation", too generic a term. Once I do click through, there is a great site for navigating the standard library which explains what packages are for, and provides various navigation elements for jumping around. Rust (https://www.rust-lang.org/learn): ======================================= - A link to a book - A link to a course - A link to rust by example (note the support for 3 different kinds of learning styles) - Core documentation - The standard library (here is, by way of being the standard library, an opinion I can borrow for how things are done). - (more links I skipped because I don't know rust, and I"d start with the above) Overall, I am left feeling like I know where I would start depending on how I want to learn, and have a quick reference to the standard library's API. Once I click through to the standard library, it suggests to me how to read it, and addresses the meta-question of what I'm looking at. I haven't used this site, but clicking around, it appears to have decent navigation elements for jumping around. Python (https://www.python.org/doc/): ===================================== - A blurb on how the different ways to consume the documentation. - Links grouped by self-reported expertise with the language If I click on Beginner's guide: - Link to explanation of what Python is - Blurb on how to get Python - Links for non-programmers to learn - Links for programmers to learn - Acknowledgment that I've been reading wiki pages. I now have an explanation for why what I've been reading feels cobbled together. - A link to a separate beginner's guide overview with more general information about the language. - A long list of books, websites, and tutorials (note there is no opinion given on which I should begin with) Overall, I am left feeling overwhelmed, and like I must independently find a curated tutorial which will give me opinions I can use until I can form my own. But wait! Had I clicked on "Python Docs" instead of "Beginner's Guide", I get something much easier to consume: - A Tutorial which simply states "start here". As a newbie, OK! - This looks like a book - Library reference - Language reference - General links to support usage This is not overwhelming, and I feel like I have a small enough set of options to click through that I can find what I need. Further, it looks like a curated opinion of how I should do things, and in what order. -- Katherine