Re: Guile documentation

[Blake Shaw <blake@sweatshoppe.org>]

[-- Attachment #1: Type: text/plain, Size: 2018 bytes --]

Hi Ludo,

(replying to this email from my other email address because I can't seem to
find it in gnus, which I only recently switched to)

For sure. I'm preparing a little document that provides an analysis of pain
points in the docs, which I'll hopefully have done by the end of this week
and can send to the group. I'll be mostly focused on the general
organizational structure of the docs and will offer solutions that if
everyone agrees to I'll go ahead and start putting to work.

Ez,
Blake

On Tue, Dec 21, 2021, 01:57 Ludovic Courtès <ludo@gnu.org> wrote:

> Hi Blake,
>
> Blake Shaw <blake@nonconstructivism.com> skribis:
>
> > While I've come to love Guile, compared to my experience with Racket its
> > been quite burdensome for me to get in the hang of, something I attribute
> > primarily to the structure of the docs, and not due to it being in any
> > way more difficult than Racket. While with Racket I was writing
> > useful programs in the standard #lang within my first week, with Guile
> > I often find that what should be almost trivial winds up with a lot of
> > time lost just trying to navigate and understand the docs. When I do
> > figure things out, it turns out to be no more difficult than the
> equivalent
> > in Racket, but a lack of consistency in the path that leads there in the
> > docs cause hangups, which has made trivial scripts that should take an
> hour
> > become weekend projects.
>
> IWBN if we could take advantage of your fresh eye to restructure the
> Guile manual in a way that makes it more convenient.
>
> Guile has changed a lot since the manual was initially written, a lot of
> sections were added, some removed, but we probably didn’t take the time
> to sit down and see how to restructure it accordingly.
>
> So if you have a specific structure in mind, or if you remember
> precisely what was hard to find and located in a unexpected section,
> please let’s take advantage of that!
>
> Thanks,
> Ludo’.
>
>

[-- Attachment #2: Type: text/html, Size: 2622 bytes --]