Proposal: Deep Dive into the Guile Docs & Makeover Proposal

Proposal: Deep Dive into the Guile Docs & Makeover Proposal

[Blake Shaw]

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 rende
 ring 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 B
 oris Groys prior to the COVID-19 pandemic.

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

[Neil Jerram]

Hi Blake,

On Tue, 8 Feb 2022 at 08:55, Blake Shaw <blake@nonconstructivism.com> wrote:
> [...]
>
> 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.

Speaking as one of the past authors of the manual, I look forward to
hearing your thoughts.  It is genuinely challenging to present this
amount of material and explain its complexity, and there is no reason
at all to consider any current arrangement as cast in stone.  Thanks
for thinking about this.

Best wishes,
    Neil

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

[Jérémy Korwin-Zmijowski]

[-- Attachment #1.1.1: Type: text/plain, Size: 4230 bytes --]

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,

Jérémy

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

[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 2525 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 665 bytes --]

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

[Blake Shaw]

Neil Jerram <neiljerram@gmail.com> writes:

> Speaking as one of the past authors of the manual, I look forward to
> hearing your thoughts.  It is genuinely challenging to present this
> amount of material and explain its complexity, and there is no reason
> at all to consider any current arrangement as cast in stone.  Thanks
> for thinking about this.
>
> Best wishes,
>     Neil

for sure. on the guix list a lot of people expressed their
frustrations (many which I share to be sure, which is why I'm drawn to
work on this), and some suggested solutions of "we should follow x
format". while I understand that sentiment, I as a recovering academic
who has helped friends with countless dissertations I also realize that
too hasty judgements in an editing process can lead to frustrations
which ultimately stall progress. nonetheless, I'm pretty confident that
most of my proposal will resonate with the newcomers and old timers
alike, and folks will agree to let me move forward without getting
bogged down in bikeshedding.

it's been quite a trip learning guile! and I'm happy I've put the effort
into it and hope I can contribute in such a way that will make it a
smoother process for future newcomers :)

-- 
“In girum imus nocte et consumimur igni”

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

[Blake Shaw]

Jérémy Korwin-Zmijowski <jeremy@korwin-zmijowski.fr> writes:

> 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

I can totally relate! That succinctly captures part of the core
issue -- I might quote you on that if you don't mind ;) 

-- 
“In girum imus nocte et consumimur igni”

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

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

[Olivier Dion via General Guile related discussions]

On Tue, 08 Feb 2022, Blake Shaw <blake@nonconstructivism.com> wrote:
> * 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 instannce,
> is only 450 pages, while the Rust Book is approximately 550 pages.

Don't forget that Guile as a lot of legacy stuff in its manual.  For
example `catch/throw` -- the old way of doing exception, althought it's
not clear what new projects should use -- is documented there.  There's
also the details of its implementation, indices, appendices, functions
in C, many SRFI and modules.  So it's true that scheme is a very simple
language, but Guile is not only Scheme.

I think there's certainly things that could be trim away to save some
space, maybe some restructuration, but I think that overall the manual
is great when you get use to it.

In my opinion, the thing that lack in the manual is a complete "How to
setup a project" example that is a more complex project than the tortoise
tutorial.  Having this section with condensed informations would be
easier for newbies than sparsed informations across hundreds of pages.
I had to learn that the hardway by reading multiple times the manual, and
looking at Guix and Guile source code.

-- 
Olivier Dion
Polymtl

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

[Blake Shaw]

james <james@jamescm.co.uk> writes:

> 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.
Great! I'm glad to hear that there is lots of interest and look forward
to hearing any feedback you might have to offer :)
-- 
“In girum imus nocte et consumimur igni”

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

[Daniel Tornabene]

just a simple guile user here, sitting next to my printed out 2.2.6 manual.
I'm interested in this topic as well though I'd say my own experience with
the documentation is less a problem with it as it is then with its
organization. Perhaps I'm an anomaly, but I enjoy and appreciate a manual
with significant, bordering on completeness of coverage of not simply the
language, but the relevant api.  I'd also add that the small examples
littered throughout the text which add to the length have however been
quite helpful to me personally, and demonstrating multiple possible paths
one might take given a language construct is a good thing in a lisp,
especially one that attempts to be as approachable as guile does. The
comparisons to racket and rust printed manuals are enlightening though, and
I'd be very interested in a "close reading", as it were, that susses out
the structural and stylistic details in a comparative way. Successfully
done that in and of itself would be both a major accomplishment for our
corner of the PL world and other software communities with a serious
commitment to documentation and even to non programmers wanting to
understand how such complicated endeavours such as a community developed
programming language effectively communicates information and practices.

On Tue, Feb 8, 2022 at 9:01 AM Blake Shaw <blake@nonconstructivism.com>
wrote:

> Neil Jerram <neiljerram@gmail.com> writes:
>
> > Speaking as one of the past authors of the manual, I look forward to
> > hearing your thoughts.  It is genuinely challenging to present this
> > amount of material and explain its complexity, and there is no reason
> > at all to consider any current arrangement as cast in stone.  Thanks
> > for thinking about this.
> >
> > Best wishes,
> >     Neil
>
> for sure. on the guix list a lot of people expressed their
> frustrations (many which I share to be sure, which is why I'm drawn to
> work on this), and some suggested solutions of "we should follow x
> format". while I understand that sentiment, I as a recovering academic
> who has helped friends with countless dissertations I also realize that
> too hasty judgements in an editing process can lead to frustrations
> which ultimately stall progress. nonetheless, I'm pretty confident that
> most of my proposal will resonate with the newcomers and old timers
> alike, and folks will agree to let me move forward without getting
> bogged down in bikeshedding.
>
> it's been quite a trip learning guile! and I'm happy I've put the effort
> into it and hope I can contribute in such a way that will make it a
> smoother process for future newcomers :)
>
> --
> “In girum imus nocte et consumimur igni”
>
>

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

[Blake Shaw]

Daniel Tornabene <d.t.peters777@gmail.com> writes:

> just a simple guile user here, sitting next to my printed out 2.2.6
> manual. I'm interested in this topic as well though I'd say my own
> experience with the documentation is less a problem with it as it is
> then with its organization. Perhaps I'm an anomaly, but I enjoy and
> appreciate a manual with significant, bordering on completeness of
> coverage of not simply the language, but the relevant api.  I'd also
> add that the small examples littered throughout the text which add to
> the length have however been quite helpful to me personally, and
> demonstrating multiple possible paths one might take given a language
> construct is a good thing in a lisp, especially one that attempts to
> be as approachable as guile does. The comparisons to racket and rust
> printed manuals are enlightening though, and I'd be very interested in
> a "close reading", as it were, that susses out the structural and
> stylistic details in a comparative way. Successfully done that in and
> of itself would be both a major accomplishment for our corner of the
> PL world and other software communities with a serious commitment to
> documentation and even to non programmers wanting to understand how
> such complicated endeavours such as a community developed programming
> language effectively communicates information and practices. 
>

for sure, just to clarify as a few folks have commented on this --
& so it seems the summary i provided may have been misleading -- my
talk will deal primarily with the structure of the docs, not what can
be cut out. i'm really focused here on the user experience, and cutting
out not length but instead inconsistencies: in language, layout, order,
and style so that users can anticipate a general cadence and thus
navigate with greater ease. in fact, i think the end result may be a
longer manual, but one in which users will have a simplified mental
map, so that amidst hacking you can navigate whether by paper of
texinfo to what you're looking for, and be in and out, back to the repl
as seamlessly as possible. the hope is to cut out downtime caused while
consulting the docs, while also preserving the deeper more essayistic
nuggets for when its time to take a plunge. 

i will offer suggestions for sets of guidelines dealing with various
aspects of structure, that intend to both add and preserve existing
structure. so it's kind of a 'functor' approach to structuring the
docs. this is also where the feedback session will be key, as longtime
users will have the knowledge of what would be *objectively bad*.

so in a sense, I will offer *weak* or abstract guidelines, and for those
that the community agrees are beneficial we should focus on collectively
strengthening them such that they may compose as a system that is
general, concrete, and true to the language itself. 

-- 
“In girum imus nocte et consumimur igni”

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

[Daniel Tornabene]

Very much agree with "How to setup a project" example, I should consider
offering my own example at some point after Blake has worked through his
approach.  Really onboard with this comment overall, the fact that C
interop is included directly in the manual is important, and something I've
been meaning to write about myself from a different direction for some time
now, and I wasn't even aware of the catch/throw change, a perfect thing to
highlight or restructure.

On Tue, Feb 8, 2022 at 10:13 AM Olivier Dion via General Guile related
discussions <guile-user@gnu.org> wrote:

> On Tue, 08 Feb 2022, Blake Shaw <blake@nonconstructivism.com> wrote:
> > * 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 instannce,
> > is only 450 pages, while the Rust Book is approximately 550 pages.
>
> Don't forget that Guile as a lot of legacy stuff in its manual.  For
> example `catch/throw` -- the old way of doing exception, althought it's
> not clear what new projects should use -- is documented there.  There's
> also the details of its implementation, indices, appendices, functions
> in C, many SRFI and modules.  So it's true that scheme is a very simple
> language, but Guile is not only Scheme.
>
> I think there's certainly things that could be trim away to save some
> space, maybe some restructuration, but I think that overall the manual
> is great when you get use to it.
>
> In my opinion, the thing that lack in the manual is a complete "How to
> setup a project" example that is a more complex project than the tortoise
> tutorial.  Having this section with condensed informations would be
> easier for newbies than sparsed informations across hundreds of pages.
> I had to learn that the hardway by reading multiple times the manual, and
> looking at Guix and Guile source code.
>
> --
> Olivier Dion
> Polymtl
>
>

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

[Daniel Tornabene]

Looking forward to your talk Blake, don't worry, the gist came across the
first time I was just offering my own experience and opinions of the
documentation. Genuinely excited to see what you come up with,
documentation is one of my favorite things in free software actually

On Tue, Feb 8, 2022 at 10:59 AM Blake Shaw <blake@nonconstructivism.com>
wrote:

> Daniel Tornabene <d.t.peters777@gmail.com> writes:
>
> > just a simple guile user here, sitting next to my printed out 2.2.6
> > manual. I'm interested in this topic as well though I'd say my own
> > experience with the documentation is less a problem with it as it is
> > then with its organization. Perhaps I'm an anomaly, but I enjoy and
> > appreciate a manual with significant, bordering on completeness of
> > coverage of not simply the language, but the relevant api.  I'd also
> > add that the small examples littered throughout the text which add to
> > the length have however been quite helpful to me personally, and
> > demonstrating multiple possible paths one might take given a language
> > construct is a good thing in a lisp, especially one that attempts to
> > be as approachable as guile does. The comparisons to racket and rust
> > printed manuals are enlightening though, and I'd be very interested in
> > a "close reading", as it were, that susses out the structural and
> > stylistic details in a comparative way. Successfully done that in and
> > of itself would be both a major accomplishment for our corner of the
> > PL world and other software communities with a serious commitment to
> > documentation and even to non programmers wanting to understand how
> > such complicated endeavours such as a community developed programming
> > language effectively communicates information and practices.
> >
>
> for sure, just to clarify as a few folks have commented on this --
> & so it seems the summary i provided may have been misleading -- my
> talk will deal primarily with the structure of the docs, not what can
> be cut out. i'm really focused here on the user experience, and cutting
> out not length but instead inconsistencies: in language, layout, order,
> and style so that users can anticipate a general cadence and thus
> navigate with greater ease. in fact, i think the end result may be a
> longer manual, but one in which users will have a simplified mental
> map, so that amidst hacking you can navigate whether by paper of
> texinfo to what you're looking for, and be in and out, back to the repl
> as seamlessly as possible. the hope is to cut out downtime caused while
> consulting the docs, while also preserving the deeper more essayistic
> nuggets for when its time to take a plunge.
>
> i will offer suggestions for sets of guidelines dealing with various
> aspects of structure, that intend to both add and preserve existing
> structure. so it's kind of a 'functor' approach to structuring the
> docs. this is also where the feedback session will be key, as longtime
> users will have the knowledge of what would be *objectively bad*.
>
> so in a sense, I will offer *weak* or abstract guidelines, and for those
> that the community agrees are beneficial we should focus on collectively
> strengthening them such that they may compose as a system that is
> general, concrete, and true to the language itself.
>
> --
> “In girum imus nocte et consumimur igni”
>

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

[Christine Lemmer-Webber]

Lol, wish I had seen this before I shot off my other email.  This is
great!  Glad to see a lot of overlap between our emails.

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

[Blake Shaw]

hiya guix,

my apologies for not turning my presentation yet! I know people
expressed excitement about it so I just want to give you a heads up that
I just finished it, but alas I'm too tired to record the video now. but
I will do it ang get it turned in first thing in the morning.

but i think it will be worth the wait. if you don't want to do your next
presentation from the REPL after seeing this, I'll personally refund
your guix-days ticket.

sorry again and thanks for the patience, I had to deadlines converge at
this moment and had to prioritize.

best,
blake
-- 
“In girum imus nocte et consumimur igni”

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”

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

[Olivier Dion via General Guile related discussions]

On Thu, 17 Feb 2022, Blake Shaw <blake@nonconstructivism.com> wrote:

> looking forward to any feedback.

Some things that I think could use some improvement:

     When you play a video while you're talking, make sure that the
     volume of the video is very low so we can still hear you.  For
     example, around 4.20 I can't hear you anymore (headphone).  At
     least the music is good.

     There's time where you say Guix when you meant Guile or Scheme I
     think.  For example around 13.40, you show a Git tree as a S-exp
     and refer to Guix.

     Looks like there's a latency between the audio and video.  Maybe
     it's peertube and not your recorder.

     If you use the REPL again for a presentation that is presented
     live, I would suggest to add page number so that it's easier to ask
     questions and reference the good slide.  In theory, one can use the
     $* variable of the REPL for that also.

The very good points of your presentation I think are:

  Your language is impeccable and very cleared/articulated.

  I like that you show your real world usage of Guile.  I feel that it's
  very important to show what Guile is capable of and that it can be
  used in a professional working environment.

Overall, a great presentation.

For your `scribble jam` project, maybe you should look into
guile-chickadee <https://dthompson.us/projects/chickadee.html>.  It's a
game development toolkit -- based on guile-opengl -- which I think
support most of what you want.  So you could use it in some way for your
project.

Other comments:

      For `Initialization with C` I would call it `C runtime initialization`.

      IMO, `Snarfing macro` should be in the same section as FFI.

      `Scheduling` -> `Multi-Threading` | `Parallelism`.

      `GOOPS` should be under `Guile Modules` or renamed to `Object
      Oriented Programming` like `Functionnal programming`.

      SXML is not just used in Web.  So I'm not sure if it should be
      under the same section.  Perhaps under parsing?

      `File Tree Walk` moved to `File System` and rename `POSIX/File System` 
      to just `File System`.

Best regards,
old

-- 
Olivier Dion
Polymtl

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

[Blake Shaw]

Olivier Dion <olivier.dion@polymtl.ca> writes:

> On Thu, 17 Feb 2022, Blake Shaw <blake@nonconstructivism.com> wrote:
>
>> looking forward to any feedback.
>
> Some things that I think could use some improvement:
>
>      When you play a video while you're talking, make sure that the
>      volume of the video is very low so we can still hear you.  For
>      example, around 4.20 I can't hear you anymore (headphone).  At
>      least the music is good.
>
>      There's time where you say Guix when you meant Guile or Scheme I
>      think.  For example around 13.40, you show a Git tree as a S-exp
>      and refer to Guix.
>
>      Looks like there's a latency between the audio and video.  Maybe
>      it's peertube and not your recorder.
>
>      If you use the REPL again for a presentation that is presented
>      live, I would suggest to add page number so that it's easier to ask
>      questions and reference the good slide.  In theory, one can use the
>      $* variable of the REPL for that also.
>
noted! first screencast on Guix so a few issues I didn't anticipated,
I'll keep them in mind for next time.
> The very good points of your presentation I think are:
>
>   Your language is impeccable and very cleared/articulated.
>
>   I like that you show your real world usage of Guile.  I feel that it's
>   very important to show what Guile is capable of and that it can be
>   used in a professional working environment.
>
> Overall, a great presentation.
>
thanks!
> For your `scribble jam` project, maybe you should look into
> guile-chickadee <https://dthompson.us/projects/chickadee.html>.  It's a
> game development toolkit -- based on guile-opengl -- which I think
> support most of what you want.  So you could use it in some way for your
> project.
>
yes, I've looked at it, but not deeply (this was a recently commissioned
work). I won't really be getting started on scribble jam for a few
weeks, but will poke at chickadee to see if it's suitable in the meantime.

> Other comments:
>
>       For `Initialization with C` I would call it `C runtime initialization`.
>
>       IMO, `Snarfing macro` should be in the same section as FFI.
>
>       `Scheduling` -> `Multi-Threading` | `Parallelism`.
>
>       `GOOPS` should be under `Guile Modules` or renamed to `Object
>       Oriented Programming` like `Functionnal programming`.
>
>       SXML is not just used in Web.  So I'm not sure if it should be
>       under the same section.  Perhaps under parsing?
>
>       `File Tree Walk` moved to `File System` and rename `POSIX/File System` 
>       to just `File System`.
>
> Best regards,
> old

thanks for the feedback and hope you join in tomorrow.

best,
blake
-- 
“In girum imus nocte et consumimur igni”

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

[Neil Jerram]

On Thu, 17 Feb 2022 at 16:59, Blake Shaw <blake@nonconstructivism.com> wrote:
>
> https://tube.nocturlab.fr/videos/watch/2b55ca09-f0fd-4899-9cb0-9632cd90b3d1

Wow, what a great reminder of things past!  I mean "past" in the sense
that I used to be very strongly focused on this, but have not been for
some years.  The material is, happily, still very relevant in the
present, so well worth addressing how it can be improved.

I'm only about half way through the video so far, but already wanted
to mention a couple of points.

Firstly, about the Guile Recipes...  I had entirely forgotten about
that, but yes, it indicates that we were having the same kind of
conversation about a cookbook several years ago as we are now.
Undeniably the guidelines / contribution structure then did not work!
Let's hope someone can devise a better structure this time around.

Secondly, what I think is the overall reason the docs are such a
mess...  Guile has always has a central tension between Scheme-centric
and C-centric usage.

- Scheme-centric usage is:  Write your main program and most of its
code in Scheme.  When you need to use something from a C library, use
the FFI to do that, or dynamically load a shared object that exposes
function as Scheme objects and procedures.

- C-centric usage is:  You already have a big main program written in
C, and you only want to allow Scheme to get involved, at certain
points, as part of a config/customization-language-on-steroids model.
You expose some of your function as Scheme objects and procedures, and
call out to a user-configured Scheme file (which can use those objects
and procedures) at the relevant points in the C processing.

Personally, I am now a big fan of Scheme-centric + FFI, as it means
always writing Scheme and never having to hack C code.  If everyone
agreed on that, we could discard all the C-centric parts of the
manual, and focus the rest on a clearer use case.  But I very much
doubt that there is clear agreement on that.  In particular, the
C-centric usage is really Guile's original reason for existing: to act
as a universal extension language for lots of GNU programs that
already exist.

I think expressing that dichotomy, and arranging the docs as clearly
as possible while still allowing for both sides, is still our number 1
problem.

Best wishes,
     Neil

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

[Olivier Dion via General Guile related discussions]

On Sat, 19 Feb 2022, Neil Jerram <neiljerram@gmail.com> wrote:

> Personally, I am now a big fan of Scheme-centric + FFI, as it means
> always writing Scheme and never having to hack C code.  If everyone
> agreed on that, we could discard all the C-centric parts of the
> manual, and focus the rest on a clearer use case.  But I very much
> doubt that there is clear agreement on that.  In particular, the
> C-centric usage is really Guile's original reason for existing: to act
> as a universal extension language for lots of GNU programs that
> already exist.

All projects being different, I don't think this is possible.  For
example, I've added Guile bindings for Jami, which is written in C++.
FFI does not have support -- as far as I know -- for C++ std::string,
std::vector<T>, std::map<K, V>.  So it's a necessary to use more than
the FFI module.

I should add that I first started using Guile because of its easy
integration with the C runtime and clear documentation on how to
interlop it.  If it was not for that, I would probably have dismiss
Guile and select Lua instead.

TLDR: I don't think we should discard anything that is C-centric in the
manual.

-- 
Olivier Dion
Polymtl

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

[adriano]

Il giorno sab, 19/02/2022 alle 10.33 -0500, Olivier Dion via General
Guile related discussions ha scritto:
> On Sat, 19 Feb 2022, Neil Jerram <neiljerram@gmail.com> wrote:
> 
> > Personally, I am now a big fan of Scheme-centric + FFI, as it means
> > always writing Scheme and never having to hack C code.  If everyone
> > agreed on that, we could discard all the C-centric parts of the
> > manual, and focus the rest on a clearer use case.  But I very much
> > doubt that there is clear agreement on that.  In particular, the
> > C-centric usage is really Guile's original reason for existing: to
> > act
> > as a universal extension language for lots of GNU programs that
> > already exist.
> 
> All projects being different, I don't think this is possible.  For
> example, I've added Guile bindings for Jami, which is written in C++.
> FFI does not have support -- as far as I know -- for C++ std::string,
> std::vector<T>, std::map<K, V>.  So it's a necessary to use more than
> the FFI module.
> 
> I should add that I first started using Guile because of its easy
> integration with the C runtime and clear documentation on how to
> interlop it.  If it was not for that, I would probably have dismiss
> Guile and select Lua instead.
> 
> TLDR: I don't think we should discard anything that is C-centric in
> the
> manual.
> 

Probably there should be 2 distinct manuals

One for each (macro) use case

The cognitive overload for someone wanting to just get their feet wet
and then maybe grow their thing organically is frankly unfair

But even by keeping a single manual, been watching Blake's video for a
while now, he offers some suggestions about how to lessen such
cognitive overload on the poor newcomer