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 09:22:04 -0600 Message-ID: References: <87tud9olma.fsf@nonconstructivism.com> <87pmnxmvgw.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="26005"; 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:29:08 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 1nHUId-0006b4-W6 for guile-user@m.gmane-mx.org; Tue, 08 Feb 2022 18:29:07 +0100 Original-Received: from localhost ([::1]:35194 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nHUIc-0003qW-MH for guile-user@m.gmane-mx.org; Tue, 08 Feb 2022 12:29:06 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:42562) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nHSJy-0006X3-Eo for guile-user@gnu.org; Tue, 08 Feb 2022 10:22:22 -0500 Original-Received: from [2a00:1450:4864:20::12c] (port=35632 helo=mail-lf1-x12c.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nHSJv-0000CT-Hx; Tue, 08 Feb 2022 10:22:21 -0500 Original-Received: by mail-lf1-x12c.google.com with SMTP id i34so34044752lfv.2; Tue, 08 Feb 2022 07:22:17 -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=tu61ZxKSLVe8muLhvsbCQtADlRuR4nEy+DgYJg4dXLY=; b=iQwkDO1oB7TszRnF2NvdlDJdZ1tjY4znUWRznAnwem/rH8VlH/RYt3MRFqQUlG7E5V NevJuqEWV7i8aHHHa+dvL9/hYS2Ad20TNbHvmMqHUI6CupOMZOeI0SzPvbouEcBb36XJ rwAtnvtu6Ld95h3X3f4GbhIVbudYEEhKETI6HOTadhtsWpZagJs7S2zdMhwPPR3ecu2Y n5VLqQChPj45BetlrnExHDM2jiifk5bJeBUPPx0F+xOXuaXUeL17CGkBvrdoc10t9sdP pPhvxaY+iaMZaJAXYBFKUjQ5R88o1itqb+TW6cKS8NSWVYuvMT1gzum5OX426Bi+udHp Hw5A== 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=tu61ZxKSLVe8muLhvsbCQtADlRuR4nEy+DgYJg4dXLY=; b=3hmqqkuTcwApsAa6jTdmRzkET6Kz4iZcp2GG/2OD5m4aJFJlkB+H+hU0xZDszJphxc UWKLK/mqRPSScLlWQ476lCBPlWgK+ijPYvyKdcB2QNBrq2QCcPT1Q9qIx4E7sKesym1D Ey8b8LBYTVoAH+GaJuoFJ7QsggLawgxkskbNtxLTXp69WN5e7TkyLtrI/PSBpoKcUY1J AVTV7yCwYu8EhcBnwdsr2evR+vX4B/Zwr/4f3w3ZiCE9dITjwmT3F4rFlUQK0OMAA+as gjHIgMaXUq6znGGgmZMptqWXvGkMZA4IBe9+Aj5GBc+g7Xy4QV+STXa4k/ayuIPll49Y CteQ== X-Gm-Message-State: AOAM532tFHVGf/C7F1ByVlUrppzWrrnV0o2cGQb1NCUW/qZnsLsDyHfe T8TvwawQ1xD9lqNhGX9HSpxz2HQj9bBJ+MIfvQQ= X-Google-Smtp-Source: ABdhPJxGvzB0oQmNtTXklWYHB3eh2nDA2ZLO1DKbLNm37sYsLkvcamwSTRHfuLkfmjLf2RtfBi82zPXmrKdWU2Qd0gE= X-Received: by 2002:a05:6512:138a:: with SMTP id p10mr3284120lfa.4.1644333736000; Tue, 08 Feb 2022 07:22:16 -0800 (PST) In-Reply-To: <87pmnxmvgw.fsf@nonconstructivism.com> X-Host-Lookup-Failed: Reverse DNS lookup failed for 2a00:1450:4864:20::12c (failed) Received-SPF: pass client-ip=2a00:1450:4864:20::12c; envelope-from=d.t.peters777@gmail.com; helo=mail-lf1-x12c.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:18039 Archived-At: 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. On Tue, Feb 8, 2022 at 9:01 AM Blake Shaw wrote: > Neil Jerram writes: > > > Speaking as one of the past authors of the manual, I look forward to > > hearing your thoughts. It is genuinely challenging to present this > > amount of material and explain its complexity, and there is no reason > > at all to consider any current arrangement as cast in stone. Thanks > > for thinking about this. > > > > Best wishes, > > Neil > > for sure. on the guix list a lot of people expressed their > frustrations (many which I share to be sure, which is why I'm drawn to > work on this), and some suggested solutions of "we should follow x > format". while I understand that sentiment, I as a recovering academic > who has helped friends with countless dissertations I also realize that > too hasty judgements in an editing process can lead to frustrations > which ultimately stall progress. nonetheless, I'm pretty confident that > most of my proposal will resonate with the newcomers and old timers > alike, and folks will agree to let me move forward without getting > bogged down in bikeshedding. > > it's been quite a trip learning guile! and I'm happy I've put the effort > into it and hope I can contribute in such a way that will make it a > smoother process for future newcomers :) > > -- > =E2=80=9CIn girum imus nocte et consumimur igni=E2=80=9D > >