guile-user
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Daniel Tornabene
Subject: Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal
Date: Tue, 8 Feb 2022 09:22:04 -0600

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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]