From: Blake Shaw <blake@sweatshoppe.org>
To: "Ludovic Courtès" <ludo@gnu.org>
Cc: Guix Devel <guix-devel@gnu.org>, jgart <jgart@dismail.de>
Subject: Re: Guile documentation
Date: Tue, 21 Dec 2021 18:01:18 +0700 [thread overview]
Message-ID: <CAKjmbcCNuf4UMmYOvZtP=hN=VspeDgWJvZAhF1H7ZkTtcfkN=w@mail.gmail.com> (raw)
In-Reply-To: <87zgovf9va.fsf@gnu.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 --]
next prev parent reply other threads:[~2021-12-21 14:20 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-12-10 22:40 Guix Documentation Meetup Blake Shaw
2021-12-10 23:18 ` Ryan Prior
2021-12-11 18:55 ` Katherine Cox-Buday
[not found] ` <87lf0q2m7n.fsf@nonconstructivism.com>
2021-12-13 3:50 ` Katherine Cox-Buday
2021-12-30 21:52 ` adriano
2022-01-06 15:58 ` Katherine Cox-Buday
2021-12-13 8:29 ` zimoun
2021-12-14 16:01 ` Katherine Cox-Buday
2021-12-14 17:38 ` Luis Felipe
2021-12-14 17:52 ` Katherine Cox-Buday
2021-12-20 17:45 ` Guile documentation Ludovic Courtès
2021-12-21 11:01 ` Blake Shaw [this message]
2021-12-21 6:41 ` Guix Documentation Meetup adriano
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://guix.gnu.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAKjmbcCNuf4UMmYOvZtP=hN=VspeDgWJvZAhF1H7ZkTtcfkN=w@mail.gmail.com' \
--to=blake@sweatshoppe.org \
--cc=guix-devel@gnu.org \
--cc=jgart@dismail.de \
--cc=ludo@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.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
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).