[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal

From: Jérémy Korwin-Zmijowski
Subject: Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal
Date: Tue, 8 Feb 2022 11:16:33 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.5.0

Hey Blake,

I look forward to read/watch your thoughts on this topic !

Few years ago I was this newcomer navigating in the Guile Reference Manual.

I could not put a word on it precisely but I was in between the feeling of having too much info or not enough. haha

Best regards,


Le 08/02/2022 à 08:36, Blake Shaw a écrit :
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)

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.

Attachment: OpenPGP_0x700F5E0CCBB2E2D1.asc
Description: OpenPGP public key

Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]