From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Blake Shaw Newsgroups: gmane.lisp.guile.user Subject: Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal Date: Thu, 17 Feb 2022 23:58:45 +0700 Message-ID: <871r01sa4a.fsf@nonconstructivism.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="17264"; mail-complaints-to="usenet@ciao.gmane.io" Cc: , To: Original-X-From: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Thu Feb 17 17:59:09 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 1nKk7Y-0004FU-TD for guile-user@m.gmane-mx.org; Thu, 17 Feb 2022 17:59:09 +0100 Original-Received: from localhost ([::1]:50512 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nKk7X-0005KN-Kv for guile-user@m.gmane-mx.org; Thu, 17 Feb 2022 11:59:07 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:53420) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nKk7L-0005K0-LI for guile-user@gnu.org; Thu, 17 Feb 2022 11:58:55 -0500 Original-Received: from out2.migadu.com ([188.165.223.204]:18807) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nKk7I-0007yM-RI; Thu, 17 Feb 2022 11:58:55 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nonconstructivism.com; s=key1; t=1645117129; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=QahBrqAbkREshN7ta3VA7+KFfnh7RbcPzv8oaZ9evhs=; b=aO/nByy4s4fPdheBtEVnPOvpTTqbfBZ6GdbMs8xukJAE8Q3EveswjBGbDJoIn3ISKDBzud mJIhulj5wRJOZYGU+R8sRMrF8+YDf4wXpKYB7PgWz1sKcJh1B98EIHFZA4yNSZKxLQ+BBt T6l63aFIiIvPP3cqmhBRqqT1xki4Gbw= Gcc: nnimap+imap.migadu.de:sent.2022 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. X-Migadu-Flow: FLOW_OUT X-Migadu-Auth-User: nonconstructivism.com Received-SPF: pass client-ip=188.165.223.204; envelope-from=blake@nonconstructivism.com; helo=out2.migadu.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.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, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham 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:18101 Archived-At: Blake Shaw writes: hiya guix, my apologies again for the hold up in getting this video to everyone. for those who won't have time to view it, I will rehash the suggested changes in the 5 minutes before; perhaps because of the delay in being able to get this together for everyone we can view my session as more of a "birds of a feather" project. also, I unfortunately went over my allotted time by spending a bit too much time on my about me. so please feel free to skip past the first 20 minutes of the video. if you are *very* pressed for time, there is also a fair amount of Guile trivia opening onto the documentation section. if you want to cut that out as well, skipping to around the 30 minute mark should be fine. https://tube.nocturlab.fr/videos/watch/2b55ca09-f0fd-4899-9cb0-9632cd90b3d1 thanks and my apologies again; writing software freelance for a living at times makes commitments to free software difficult to uphold. looking forward to any feedback. best, blake > 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 rendering 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. > -- “In girum imus nocte et consumimur igni”