From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Neil Jerram Newsgroups: gmane.lisp.guile.user Subject: Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal Date: Tue, 8 Feb 2022 09:07:53 +0000 Message-ID: References: <87tud9olma.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="15198"; mail-complaints-to="usenet@ciao.gmane.io" Cc: guix-user@gnu.org, guile-user , guix-days@gnu.org To: Blake Shaw Original-X-From: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Tue Feb 08 10:26:26 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 1nHMlV-0003mW-AZ for guile-user@m.gmane-mx.org; Tue, 08 Feb 2022 10:26:25 +0100 Original-Received: from localhost ([::1]:41908 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nHMlU-0005Gc-CU for guile-user@m.gmane-mx.org; Tue, 08 Feb 2022 04:26:24 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:49080) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nHMTw-0004BQ-SH for guile-user@gnu.org; Tue, 08 Feb 2022 04:08:17 -0500 Original-Received: from [2607:f8b0:4864:20::d2f] (port=43846 helo=mail-io1-xd2f.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nHMTt-0000nO-JB; Tue, 08 Feb 2022 04:08:15 -0500 Original-Received: by mail-io1-xd2f.google.com with SMTP id m185so12006662iof.10; Tue, 08 Feb 2022 01:08:05 -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:content-transfer-encoding; bh=yj4D/NTzFs/uR9+qQQsFzjoU3h6d+iOcG2OBd/OaKzU=; b=OSvjk2ZAQ7aBcA2PARc8TMkEG79fGFFsYa1iRgaKmByCa0kY/e11CQWrCOZlQh+3DI yVMNeYC0mBafczMJc+5LaBibh1driWh2LU4DyjWaO0Sw5dZaIGfN3125JvR6ZBcr8S3r s0otzqKrG27QRX9IT3MXBsFjduzKXe5fAvkV3X9nIwVd48RSSNtyOi5+u0XG8tU+Kjvj cB/DYtFKvVm4z+/Ixy6KCHRDsZYG3WIzLXok7ll+nzpcIHLSwA1TU50mHTtaZQ/AZi4H 2Ua5ec132gYhyGv9luyMfqy661bY97RzV9aSLwofxr4seYBPkLkcoawzBFTn7/hfVboT vZMA== 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:content-transfer-encoding; bh=yj4D/NTzFs/uR9+qQQsFzjoU3h6d+iOcG2OBd/OaKzU=; b=iPvNW1Ytu4h8o3FwClJgUPxtczB/KjUwtb+fN6z3F0j31ce8SWMnn+NyWcWdWcthVJ 4sQzeRofKL9SnSZyfYFPN6M1LRpueXwwl1QjBepOdGmL/H9YpkeOjkGTU8tlCe9wSJAX g9iHteMcSCZEaEYo19q8wu4wEgJi/rS2LeJ0oXWwXoWMydb1DPJFbnDP3Q2wwW5FriQu /6ReFfEhCLJlo5EfdV+YoaNfdWROXa/3GZHWZgvEz8lvf8hG1zt0jRodLQP9htrnpN8a BhMFB8w7RMMW9UTJV6QhhQRl0WZ2fkmToaK5h6Mmpa0yje4z/TRNZaLB9+Uh4GhaiRqJ 1oyA== X-Gm-Message-State: AOAM5307uMCDxdXn/hqnwC0dK7sbK/gxfA+TYcYfBdVpaQFFxAlufyqL 9hxacTlJh8dOrO3PP6kCXMvrzsQTLlsHloLcSw1A/fGm X-Google-Smtp-Source: ABdhPJyunNh0jkSeE3HflJvgwIo3Csh42PyoCS2884iKTRZ8Tx7Ya+kjotSo8ErfkJc30/TvARpPeCcdMOgBsK4Jcns= X-Received: by 2002:a05:6638:1408:: with SMTP id k8mr1774145jad.267.1644311284660; Tue, 08 Feb 2022 01:08:04 -0800 (PST) In-Reply-To: <87tud9olma.fsf@nonconstructivism.com> X-Host-Lookup-Failed: Reverse DNS lookup failed for 2607:f8b0:4864:20::d2f (failed) Received-SPF: pass client-ip=2607:f8b0:4864:20::d2f; envelope-from=neiljerram@gmail.com; helo=mail-io1-xd2f.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, 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-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:18030 Archived-At: Hi Blake, On Tue, 8 Feb 2022 at 08:55, Blake Shaw wrote= : > [...] > > Serving at once as a referrence manual & API specification, the large siz= e may in part be attributed to what simultaneously makes Guile an appealing= project to contribute to, while also rendering the documentation process s= omewhat delicate: Guile is a massive collective project featuring the contr= ibutions of many authors over the course of three decades, contributions wh= ich Guilers would hate to trivialize or treat as insignificant or edit away= on a whim. Additionally, Guile comes from a long set of traditions within = Scheme hacking which itself is deep with sage wisdom spanning many pedagogi= cal philosophies and one of the greatest literature traditions of hacker cu= lture. Is it possible to perform a makeover of the Guile Documentation whil= e respecting these historical threads, at once rendering it more approachab= le for new users while not forsaking the deep nuggets of wisdom that lie th= erein? > > Since mid-December I have been mulling over these questions as newcomer, = both studying & analyzing the docs, and trying to come to grips with it's s= trengths and shortcomings. For this talk, I will present my research to the= Guix community, culminating with a plan for a full makeover of the existin= g docs which would respect the above concerns. I will use the 5 minute pres= entation to focus on the plan of action, with hopes that during the Q&A we = can come to consensus on what is to be done. The decisions made by the grou= p will form the basis of a proposal to be made to the Guile community, and = once everyone is in agreement with plans for how to move forward I will und= ertake the effort to implement the makeover proposal. 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