From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: james Newsgroups: gmane.lisp.guile.user Subject: Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal Date: Tue, 8 Feb 2022 14:45:09 +0000 Message-ID: <20220208144509.zxurkbvvqd6zwrky@arch-surface.durhamsixthformcentre.org.uk> References: <87tud9olma.fsf@nonconstructivism.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="31006"; mail-complaints-to="usenet@ciao.gmane.io" Cc: guix-user@gnu.org, guile-user@gnu.org, guix-days@gnu.org To: Blake Shaw Original-X-From: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Tue Feb 08 18:22:36 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 1nHUCJ-0007pW-Qu for guile-user@m.gmane-mx.org; Tue, 08 Feb 2022 18:22:35 +0100 Original-Received: from localhost ([::1]:50216 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nHUCI-0002gg-Lf for guile-user@m.gmane-mx.org; Tue, 08 Feb 2022 12:22:34 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:58654) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nHRkA-0004Di-Tb for guile-user@gnu.org; Tue, 08 Feb 2022 09:45:22 -0500 Original-Received: from [178.62.35.155] (port=48862 helo=jamescm.co.uk) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nHRk8-0001pX-A6 for guile-user@gnu.org; Tue, 08 Feb 2022 09:45:22 -0500 Original-Received: from localhost (unknown [217.23.238.227]) by jamescm.co.uk (Postfix) with ESMTPSA id CA36A60E21; Tue, 8 Feb 2022 14:45:15 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=jamescm.co.uk; s=mail; t=1644331515; bh=tHwZnakP/8DA5NykaBUmRC6KquxxtWMI/4Hi8hefNqg=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=GcWlIvMv5IrFJYapim6Jo+wp/zXDhe7TB+hbutwGR55BAA/vZAqQHsS17fpUAQkFF jYayzqKhmpPhw3ku17xViJ4g8zrTnz5JrMO6hM5eJG2LQOT0IVDreffPi9PTEq21Hc 4tkTUkt1SYP1+l0fp7DmSiDCkMLScBtLLlpOvi5rHL4Y7UjudJkRh5RkB9Y9NVtv/5 o0T+Epg2A4MZW4EHFUNmlKMBXFVnAsiUS99eVmAF9dCRWdASPKPKfvy9JXsjriK6++ QNL9bstqBhlK1LHuSPDKV2mZZc/uszocyV98BPW5KKls5uYpV9NpbX0lGM21orz/c+ I1tuIt6TqHFew== Content-Disposition: inline In-Reply-To: <87tud9olma.fsf@nonconstructivism.com> X-Host-Lookup-Failed: Reverse DNS lookup failed for 178.62.35.155 (failed) Received-SPF: pass client-ip=178.62.35.155; envelope-from=james@jamescm.co.uk; helo=jamescm.co.uk X-Spam_score_int: 6 X-Spam_score: 0.6 X-Spam_bar: / X-Spam_report: (0.6 / 5.0 requ) BAYES_00=-1.9, DKIM_INVALID=0.1, DKIM_SIGNED=0.1, RCVD_IN_SORBS_WEB=1.5, RDNS_NONE=0.793, SPF_HELO_PASS=-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:18038 Archived-At: On 22/02/08 02:36pm, Blake Shaw wrote: > > Dear Guix (and guile users, who I've Cc'd), > > My apologies for turning this in last minute. There had been discussion about this proposal on the guix mailing list, and I had missed that I need to submit a formal proposal until roptat mentioned it at Fosdem. Nonetheles here it is: > > * TITLE: A Deep Dive into the Guile Documentation & Makeover Proposal > * FORMAT: Standard Talk > * LENGTH: Approximately 30 minutes (pre-recorded) > > * SUMMARY: > Recent discussions on the Guix mailing list revealed that many in the Guix community have found the Guile Reference Manual difficult to navigate as newcomers. That should come as no surprise -- in PDF form, the docs span approximately /850 pages/, making it a quite hefty set of documents for an implementation of a minimal programming language like Scheme, even when compared to the documentation of relatively large PLs; the Racket Guide, for instance, is only 450 pages, while the Rust Book is approximately 550 pages. > > Serving at once as a referrence manual & API specification, the large size may in part be attributed to what simultaneously makes Guile an appealing project to contribute to, while also rendering the documentation process somewhat delicate: Guile is a massive collective project featuring the contributions of many authors over the course of three decades, contributions which 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 pedagogical philosophies and one of the greatest literature traditions of hacker culture. Is it possible to perform a makeover of the Guile Documentation while respecting these historical threads, at once ren dering it more approachable for new users while not forsaking the deep nuggets of wisdom that lie therein? > > 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 strengths and shortcomings. For this talk, I will present my research to the Guix community, culminating with a plan for a full makeover of the existing docs which would respect the above concerns. I will use the 5 minute presentation 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 group 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 undertake the effort to implement the makeover proposal. > > Additionally, as a newcomer to Guix, I will use the first 10 minutes of my talk to briefly introduce my work and how I'm using Guix & Guile to create a remotely deployed large-scale public interactive video mapping installation commissioned by the city of Singapore which will be installed in Marina Bay at the heart of the city this summer for 8 weeks from June - August 2022. > > * BIO: > Blake Shaw is a media artist and theorist most well known as one of the founders of the SWEATSHOPPE urban media art collective. His works have been shown in over 40 cities on every continent of the world (excluding Antarctica) at venues including: The Venice Biennale (2017), The Brooklyn Museum, Akademie de Kunste Berlin, The Museum of the Moving Image, The Biennial of the America, Luminato (Toronto), The Media Architecture Biennale, and the Museum of Contemporary Art Zagreb. His work have been featured in publications including The New York Times and the Atlantic, and online they have been viewed over 30 million times across various channels. He holds a Masters degree in Philosophy from the EGS Switzerland, and was pursuing a PhD in the Philosophy of Mathematics under the supervision of Boris Groys prior to the COVID-19 pandemic. > I too would like to state my interest in your talk. As someone who is relatively new to GNU Guile, I definitely see the interest in such a discussion as I do my self sometimes find the documentation a bit hard to navigate although I don't claim to have any knowledge of the history surrounding it. It does seem like a large, and perhaps a difficult task to produce a talk on the subject so I would very much be interested in seeing it.