Re: Newbie thoughts on Guile Hall + Guix
Hi Blake, I'm Adriano , it' just happens that I'm reading this message of yours from another account Il giorno mar 8 feb 2022 alle ore 14:39 Blake Shaw < bl...@nonconstructivism.com> ha scritto: > Vijay Marupudi writes: > > I don't think it's fair to say that using packages in Guile just as > > easy/hard as other languages. Python / Javascript make this incredibly > > easy, and their ecosystem is evidence for that success. Their package > > managers have flaws, but they have benefits too, and those benefits > > would be great for Guile. > > I would just like to tag onto this convo that I agree that its not fair > to say that Guile is easy and will quickly bless those who endeavor to > learn it with superpowers. My experience w/Racket was very smooth and I > got working in it very quickly. I was a contracted to work on a project in > Python a few months ago and without ever studying it I was able to > start doing production work in it (ridiculous how intuitive it is, > really). Before I started learning Guile I read Edwin Brady's book on > Idris and found Idris much easier to get from start to end of small > projects I was working on (because there is a well written book on it). > > While Guile has become my favorite programming language, it took me > several months to learn how to navigate & figure out how to navigate the > SRFIs, how to plan a program so that I can know what to expect along the > way (what features I'll need to implement myself, etc) before I was able > to get productive in it beyond the realm of Guix. And I think most would > agree that Scheme is a less advanced language than Idris (I did some > category theory in school so I have some intuition for the ideas, but > still). And to be honest, I still hit plenty of road blocks. > > There were definitely some times where I was digging around trying to > figure out how to do things and came across messages in the archives > saying "its so easy you just do [vague hand wavy explanation]". And I > found that quite frustrating, like there is an insularity meant to weed > out the bad apples. And when this topic popped up on the guix list a few > weeks ago some others expressed similar concerns, folks who are doing > very impressive work. A programming language should never make > programmers feel dumb -- it should make us feel empowered! > I personally believe this is a good chunk of why Guile wasn't as successful as Python With Guile the overall experience is extremely frustrating I've been hanging around here for years, on and off, and overall I haven't done anything, in Guile I managed to do some widgets in clojurescript, some modest datapipes in Clojure, a game of life with some 2d graphics library in Clojure I made some things in Python In Guile ? Nothing, nisba, nada I can relate to the experience of feeling frustrated about how casually some things are referred to on Guile channels Last time it was about the new exceptions But I remember I asked for an example of some usage of the APIs for web serving in Guile, some years ago I was kindly offered an example by Andy Wingo nonetheless But then I could follow up, I got lost, I don't remember why exactly, but I was ashamed to keep gong n any way Something similar happened when I asked about lazyness I don't think I've ever seen a community that suffers the curse of knowledge more than the Guile community This is why I was enticed to attempt the only video in my life about how to read a file (a basic use case) with Guile And I'm mumbling to do a new series about project management and package building And about delimited continuations And, and, and That is, my hope now is that Guile can be made into something empowering, so that it will be useful to someone else in the future rather than disempowering as it has always been (for me at least) I've been terribly frustrated about this in the past and I'm so refreshed to see you landing here, in Guile land One final note: while I have been emotional about this in the past, I believe I'm not being emotional now My remarks are not meant to disparage the Guile/Guix community, I acknowledge the generosity of this community, overall I just think that it's right and useful to raise perceived problems And I think this initiative to reconsider the structure of the manual is one of the best things that happened in a very long time After so many years I still can't tell where to look in it when I need something
Re: Newbie thoughts on Guile Hall + Guix
Chris Vine writes: > Everything is capable of improvement but the guile manual is a manual > and not I think primarily intended as a language tutorial (although > Chapter 3 of the manual does have a very cursory introduction to the > scheme language). If you are looking for a tutorial, I suggest reading > https://www.scheme.com/tspl4/ . It covers the R6RS flavour, but at the > tutorial level I don't think the various current standard flavours > (R5RS, R6RS and R7RS) matter too much. > > I would be reluctant to see the manual turned into a tutorial if that > were to mean abridging any of its current completeness. > For sure, but I didn't say anything about the manual here or anything about a tutorial. -- “In girum imus nocte et consumimur igni”
Re: Newbie thoughts on Guile Hall + Guix
On Tue, 08 Feb 2022 19:19:06 +0700 Blake Shaw wrote: > Vijay Marupudi writes: > > I don't think it's fair to say that using packages in Guile just as > > easy/hard as other languages. Python / Javascript make this incredibly > > easy, and their ecosystem is evidence for that success. Their package > > managers have flaws, but they have benefits too, and those benefits > > would be great for Guile. > > I would just like to tag onto this convo that I agree that its not fair > to say that Guile is easy and will quickly bless those who endeavor to > learn it with superpowers. My experience w/Racket was very smooth and I > got working in it very quickly. I was a contracted to work on a project in > Python a few months ago and without ever studying it I was able to > start doing production work in it (ridiculous how intuitive it is, > really). Before I started learning Guile I read Edwin Brady's book on > Idris and found Idris much easier to get from start to end of small > projects I was working on (because there is a well written book on it). > > While Guile has become my favorite programming language, it took me > several months to learn how to navigate & figure out how to navigate the > SRFIs, how to plan a program so that I can know what to expect along the > way (what features I'll need to implement myself, etc) before I was able > to get productive in it beyond the realm of Guix. And I think most would > agree that Scheme is a less advanced language than Idris (I did some > category theory in school so I have some intuition for the ideas, but > still). And to be honest, I still hit plenty of road blocks. > > There were definitely some times where I was digging around trying to > figure out how to do things and came across messages in the archives > saying "its so easy you just do [vague hand wavy explanation]". And I > found that quite frustrating, like there is an insularity meant to weed > out the bad apples. And when this topic popped up on the guix list a few > weeks ago some others expressed similar concerns, folks who are doing > very impressive work. A programming language should never make > programmers feel dumb -- it should make us feel empowered! Everything is capable of improvement but the guile manual is a manual and not I think primarily intended as a language tutorial (although Chapter 3 of the manual does have a very cursory introduction to the scheme language). If you are looking for a tutorial, I suggest reading https://www.scheme.com/tspl4/ . It covers the R6RS flavour, but at the tutorial level I don't think the various current standard flavours (R5RS, R6RS and R7RS) matter too much. I would be reluctant to see the manual turned into a tutorial if that were to mean abridging any of its current completeness.
Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal
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 wrote: > On Tue, 08 Feb 2022, Blake Shaw 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
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 wrote: > Daniel Tornabene 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 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
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 wrote: > Neil Jerram 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
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 > 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: Newbie thoughts on Guile Hall + Guix
adriano writes: > Just don't > That stuff is too low level for human beings > [...] > Anyway, I feel your frustration, I've been there myself > > Actually I've been there with Guile more than with Guix > > But still I feel you > > I hope this message of mine can sooth your frustration, to some extent > Wasn't intended for me, but I found it soothing! Somewhat off topic, but I feel like briefly relating these types of sentiment could even be useful to interject in within the Guix docs at times. There are many points of docs where the sales pitch bleeds into points far past the point of sale, so to speak. There are lots of "Guix makes this easy by x y z" deep in the docs, but the longer I've been in the community the more I've seen long time contributors relate that there are lots of points of frustration around certain things that may be called easy in the docs. If you're frustrated, and someone is there telling you what you're confused about this is simple and easy, that can come across as rubbing salt in wounds. While I share the enthusiasm, and I realize how much Guix eases things compared to traditional methods, it has been de-motivating for me at times. On the other hand, I think briefly relating, for example, "Depending on the complexity of a package, packagers at times will be exposed to low-level details that aren't traditionally meant for humans. This can be a genuinely frustrating experience..." becomes encouraging. Hope that makes sense, just food for thought! We could all use a pat on the back at times, especially given the human-ness of a project like guix that is waivers between the social and solitary :) -- “In girum imus nocte et consumimur igni”
Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal
james 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
On Tue, 08 Feb 2022, Blake Shaw 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
Neil Jerram 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
Jérémy Korwin-Zmijowski 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: Newbie thoughts on Guile Hall + Guix
Vijay Marupudi writes: > I don't think it's fair to say that using packages in Guile just as > easy/hard as other languages. Python / Javascript make this incredibly > easy, and their ecosystem is evidence for that success. Their package > managers have flaws, but they have benefits too, and those benefits > would be great for Guile. I would just like to tag onto this convo that I agree that its not fair to say that Guile is easy and will quickly bless those who endeavor to learn it with superpowers. My experience w/Racket was very smooth and I got working in it very quickly. I was a contracted to work on a project in Python a few months ago and without ever studying it I was able to start doing production work in it (ridiculous how intuitive it is, really). Before I started learning Guile I read Edwin Brady's book on Idris and found Idris much easier to get from start to end of small projects I was working on (because there is a well written book on it). While Guile has become my favorite programming language, it took me several months to learn how to navigate & figure out how to navigate the SRFIs, how to plan a program so that I can know what to expect along the way (what features I'll need to implement myself, etc) before I was able to get productive in it beyond the realm of Guix. And I think most would agree that Scheme is a less advanced language than Idris (I did some category theory in school so I have some intuition for the ideas, but still). And to be honest, I still hit plenty of road blocks. There were definitely some times where I was digging around trying to figure out how to do things and came across messages in the archives saying "its so easy you just do [vague hand wavy explanation]". And I found that quite frustrating, like there is an insularity meant to weed out the bad apples. And when this topic popped up on the guix list a few weeks ago some others expressed similar concerns, folks who are doing very impressive work. A programming language should never make programmers feel dumb -- it should make us feel empowered! [end rant, thanks for humoring me] -- “In girum imus nocte et consumimur igni”
Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal
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 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. OpenPGP_0x700F5E0CCBB2E2D1.asc Description: OpenPGP public key OpenPGP_signature Description: OpenPGP digital signature
Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal
Hi Blake, On Tue, 8 Feb 2022 at 08:55, Blake Shaw 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 > 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
Proposal: Deep Dive into the Guile Docs & Makeover Proposal
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 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.
