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 <bl...@nonconstructivism.com> wrote: > Neil Jerram <neiljer...@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” > >
