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

[james]

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 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.
> 

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.