From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Daniel Tornabene Newsgroups: gmane.lisp.guile.user Subject: Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal Date: Tue, 8 Feb 2022 11:28:34 -0600 Message-ID: References: <8735ktpa56.fsf@nonconstructivism.com> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="10268"; mail-complaints-to="usenet@ciao.gmane.io" Cc: guix-user@gnu.org, guix-days@gnu.org, guile-user To: Blake Shaw Original-X-From: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Tue Feb 08 18:56:50 2022 Return-path: Envelope-to: guile-user@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nHUjS-0002TU-AG for guile-user@m.gmane-mx.org; Tue, 08 Feb 2022 18:56:50 +0100 Original-Received: from localhost ([::1]:48236 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nHUjR-0000w9-2b for guile-user@m.gmane-mx.org; Tue, 08 Feb 2022 12:56:49 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:53078) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nHUIT-0004gs-8M for guile-user@gnu.org; Tue, 08 Feb 2022 12:29:00 -0500 Original-Received: from [2a00:1450:4864:20::131] (port=42552 helo=mail-lf1-x131.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nHUIN-0004h2-5n; Tue, 08 Feb 2022 12:28:56 -0500 Original-Received: by mail-lf1-x131.google.com with SMTP id k13so34662597lfg.9; Tue, 08 Feb 2022 09:28:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=i/0KyihCKGvuC059QIe6FOcKuDKngJKWbobZZn83t+A=; b=Ufd6pwhOcao8Km0oZiB+Z93JETEvTJMmDg33RP3p3DgIKadA8ZWi6Bo9lVL0K+1OjD J7U+Q3y8ajTuxOZ/wXCGX7eJrtIYro6Miiv3gPWaJn5FtFZgvRcX4apRMXilk2rcsq+F zLQreiAAWyXkFk4baUgw3Y07tMH3UI73wIe/F5/HyCvx8GE1gq3I/m3deQjNbMrbRbF9 VGlaxOPUi51erOlB1DFjQtvRB759aKRbC38VycsEHTuo0b1mxvLXjI92U9I5Yy7LNCcu 3NNXwlZE6RCPgotjs6qxnQccewFdFfZl1fFbmFNdMo5Q+8iJXU6vaijz4Rru2lxlBv8g r7RQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=i/0KyihCKGvuC059QIe6FOcKuDKngJKWbobZZn83t+A=; b=LwPHWkbJOpKCHD3HoHNl8pqocSYFq/zCNQsMbwixWnb3f9aiKb/bfkh3ZkpUBVaTcd 6dinMl/7kEKyLJcLksBXOiXdgQL8cv+0ziG51v21rYUOLSIp/NidFA+J8zKYViI0YkEK 8vCIKn8wz/ISxVK14+xnh22RZiwOm5EiSwSF/pcO4o/KHpgQNt1njENPOxn+10wRgwHM sZZWe0Y4zluMvtJFuuLZ1SybqxjRDAa908C2W9m+qx3JUsTPrmm9Gdc2+tVwR7zUkdh1 bY97TdGMyoJ+3NoFvf09ePBDgTGPO1IZ/OPYHGqoKKXhQKGJsg3ag5PhPMLlzlenUGJP 83HA== X-Gm-Message-State: AOAM531+Fn+igNpKEsXCVrYpxuj57F7eq8q1VzeCM/znbN+eSnEeZBz2 LW48zPz/teBGQiPoBgPUABfqmt/Mi51boK2p4Q0= X-Google-Smtp-Source: ABdhPJw6nVepzIAC/yCa0HMklOpR8SWz49GCwMu28mV0WEs8dA2SNkn9AA0SlHdcCq3l9XkOUTzvZOML7gLfncc39Vk= X-Received: by 2002:a05:6512:138a:: with SMTP id p10mr3613400lfa.4.1644341326917; Tue, 08 Feb 2022 09:28:46 -0800 (PST) In-Reply-To: <8735ktpa56.fsf@nonconstructivism.com> X-Host-Lookup-Failed: Reverse DNS lookup failed for 2a00:1450:4864:20::131 (failed) Received-SPF: pass client-ip=2a00:1450:4864:20::131; envelope-from=d.t.peters777@gmail.com; helo=mail-lf1-x131.google.com X-Spam_score_int: -10 X-Spam_score: -1.1 X-Spam_bar: - X-Spam_report: (-1.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, FREEMAIL_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, PDS_HP_HELO_NORDNS=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RDNS_NONE=0.793, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=no autolearn_force=no X-Spam_action: no action X-Content-Filtered-By: Mailman/MimeDel 2.1.29 X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Original-Sender: "guile-user" Xref: news.gmane.io gmane.lisp.guile.user:18041 Archived-At: Looking forward to your talk Blake, don't worry, the gist came across the first time I was just offering my own experience and opinions of the documentation. Genuinely excited to see what you come up with, documentation is one of my favorite things in free software actually On Tue, Feb 8, 2022 at 10:59 AM Blake Shaw wrote: > Daniel Tornabene writes: > > > just a simple guile user here, sitting next to my printed out 2.2.6 > > manual. I'm interested in this topic as well though I'd say my own > > experience with the documentation is less a problem with it as it is > > then with its organization. Perhaps I'm an anomaly, but I enjoy and > > appreciate a manual with significant, bordering on completeness of > > coverage of not simply the language, but the relevant api. I'd also > > add that the small examples littered throughout the text which add to > > the length have however been quite helpful to me personally, and > > demonstrating multiple possible paths one might take given a language > > construct is a good thing in a lisp, especially one that attempts to > > be as approachable as guile does. The comparisons to racket and rust > > printed manuals are enlightening though, and I'd be very interested in > > a "close reading", as it were, that susses out the structural and > > stylistic details in a comparative way. Successfully done that in and > > of itself would be both a major accomplishment for our corner of the > > PL world and other software communities with a serious commitment to > > documentation and even to non programmers wanting to understand how > > such complicated endeavours such as a community developed programming > > language effectively communicates information and practices. > > > > for sure, just to clarify as a few folks have commented on this -- > & so it seems the summary i provided may have been misleading -- my > talk will deal primarily with the structure of the docs, not what can > be cut out. i'm really focused here on the user experience, and cutting > out not length but instead inconsistencies: in language, layout, order, > and style so that users can anticipate a general cadence and thus > navigate with greater ease. in fact, i think the end result may be a > longer manual, but one in which users will have a simplified mental > map, so that amidst hacking you can navigate whether by paper of > texinfo to what you're looking for, and be in and out, back to the repl > as seamlessly as possible. the hope is to cut out downtime caused while > consulting the docs, while also preserving the deeper more essayistic > nuggets for when its time to take a plunge. > > i will offer suggestions for sets of guidelines dealing with various > aspects of structure, that intend to both add and preserve existing > structure. so it's kind of a 'functor' approach to structuring the > docs. this is also where the feedback session will be key, as longtime > users will have the knowledge of what would be *objectively bad*. > > so in a sense, I will offer *weak* or abstract guidelines, and for those > that the community agrees are beneficial we should focus on collectively > strengthening them such that they may compose as a system that is > general, concrete, and true to the language itself. > > -- > =E2=80=9CIn girum imus nocte et consumimur igni=E2=80=9D >