unofficial mirror of guile-user@gnu.org 
 help / color / mirror / Atom feed
From: Daniel Tornabene <d.t.peters777@gmail.com>
To: Blake Shaw <blake@nonconstructivism.com>
Cc: guix-user@gnu.org, guix-days@gnu.org, guile-user <guile-user@gnu.org>
Subject: Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal
Date: Tue, 8 Feb 2022 09:22:04 -0600	[thread overview]
Message-ID: <CAMo=-SAGe_4wY0V6c=WqEw=k+rVcTmimfTrZJt-bQ_kqBKyuxg@mail.gmail.com> (raw)
In-Reply-To: <87pmnxmvgw.fsf@nonconstructivism.com>

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	other threads:[~2022-02-08 15:22 UTC|newest]

Thread overview: 20+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-02-08  7:36 Proposal: Deep Dive into the Guile Docs & Makeover Proposal Blake Shaw
2022-02-08  9:07 ` Neil Jerram
2022-02-08 11:46   ` Blake Shaw
2022-02-08 15:22     ` Daniel Tornabene [this message]
2022-02-08 10:16 ` Jérémy Korwin-Zmijowski
2022-02-08 14:45 ` james
2022-02-08 15:08 ` Olivier Dion via General Guile related discussions
2022-02-08 17:25   ` Daniel Tornabene
2022-02-10 17:20 ` Christine Lemmer-Webber
  -- strict thread matches above, loose matches on Subject: below --
2022-02-08 13:06 Blake Shaw
2022-02-08 15:21 Blake Shaw
2022-02-08 16:59 Blake Shaw
2022-02-08 17:28 ` Daniel Tornabene
2022-02-16 22:06 Blake Shaw
2022-02-17 16:58 Blake Shaw
2022-02-18 17:48 ` Olivier Dion via General Guile related discussions
2022-02-19 12:17 ` Neil Jerram
2022-02-19 15:33   ` Olivier Dion via General Guile related discussions
2022-02-19 17:35     ` adriano
2022-02-18 18:05 Blake Shaw

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/guile/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CAMo=-SAGe_4wY0V6c=WqEw=k+rVcTmimfTrZJt-bQ_kqBKyuxg@mail.gmail.com' \
    --to=d.t.peters777@gmail.com \
    --cc=blake@nonconstructivism.com \
    --cc=guile-user@gnu.org \
    --cc=guix-days@gnu.org \
    --cc=guix-user@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).