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

[Blake Shaw]

Blake Shaw <blake@nonconstructivism.com> 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”