From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id UBqiApDiwWFPYwAAgWs5BA (envelope-from ) for ; Tue, 21 Dec 2021 15:20:00 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1 with LMTPS id oK3XOY/iwWG4agAAbx9fmQ (envelope-from ) for ; Tue, 21 Dec 2021 14:19:59 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id AB31435442 for ; Tue, 21 Dec 2021 15:19:59 +0100 (CET) Received: from localhost ([::1]:40362 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mzfzi-00070n-OZ for larch@yhetil.org; Tue, 21 Dec 2021 09:19:58 -0500 Received: from eggs.gnu.org ([209.51.188.92]:43354) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mzctk-0003mp-5f for guix-devel@gnu.org; Tue, 21 Dec 2021 06:01:36 -0500 Received: from [2607:f8b0:4864:20::630] (port=44977 helo=mail-pl1-x630.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mzctg-0004Tm-SR for guix-devel@gnu.org; Tue, 21 Dec 2021 06:01:35 -0500 Received: by mail-pl1-x630.google.com with SMTP id q17so10452776plr.11 for ; Tue, 21 Dec 2021 03:01:31 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sweatshoppe-org.20210112.gappssmtp.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=Q+cX7ZcHaQfwYFrskEYw2rty0+eq0ZcarGGDGw6L4Vw=; b=FGtBIcDILCuodu5j56QzusNkuHrKNoynqksYzWRKoQf1fFR5rFEZu61vd5WCuAX/wQ P+/416UKdlSbwsF39VXZpazOunx5MpjxW5Babm0HTcJumzQEcDIhG2qJQBVoJeUPUdsr ZPJX7KzQd1lPDmdTZtyMvkit0DI/448O1cT1fEClKe2ICElGnaZeXt3Mj2gN8th5nA0V qJ0fOql7ZOr/S5fGCk4ahQvuoOBiRofCjQNQRdSHnONR802G2MYKXZxfSNQriuGjVP4F F0MdmvMhQc9jG9844dPaIuYd3yoRpMkf78OlafRBUUKZRj55tib5mIbisYjhN5l15/mr YrWQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=Q+cX7ZcHaQfwYFrskEYw2rty0+eq0ZcarGGDGw6L4Vw=; b=MgwpYx6eM+h8qMlX9kBz7U3ipnzCbk7PcDTqSvYs5zo/m6lNLT3+9Aih9dg83DeGN9 6sBrBNUvw1dPXnErNFJp1bdiNwhIjTPMhWK51mwK+sAVO3YxqwRnJ3DOwSqLeYcv6XrO z+WNfCNkyiGJ/+9kuFm74fcJ3QF8gVF5l5S0qIRFKPLqbXdr/ZI0lw17eGmzmCg5Rs4K asWua8XwDxnBJazNmBFo35EqhFanfQvH+o+nVWpZ6s50MI8QCFiFr3uGM3QlbY0Nu1+B gBABZKDpwoaObtoxg7gDHTwfQx3oZqNNpz13J9zJG9RF3yda0sHdpBOs95u64PIie7sl 5H/A== X-Gm-Message-State: AOAM532Wg83RHkrJ8QN2rFPRFE5A22qe5ArZJzWXk59eO5leLI29AxXZ 5C8hBjukAsMFxae2GUfP1SDOhZpNYyN8las5C8r915xDPsE= X-Google-Smtp-Source: ABdhPJy92EKJFwKNNA/16tNp+SABHCL/ymMiMiOnxguEKyuoV5D6y0e+YSmBCzFq+Fv4mXgRjN38xDcL1rcj9wAufRk= X-Received: by 2002:a17:902:c643:b0:148:c26e:cb30 with SMTP id s3-20020a170902c64300b00148c26ecb30mr2525662pls.25.1640084490828; Tue, 21 Dec 2021 03:01:30 -0800 (PST) MIME-Version: 1.0 References: <87y24s13u8.fsf@nonconstructivism.com> <87zgovf9va.fsf@gnu.org> In-Reply-To: <87zgovf9va.fsf@gnu.org> From: Blake Shaw Date: Tue, 21 Dec 2021 18:01:18 +0700 Message-ID: Subject: Re: Guile documentation To: =?UTF-8?Q?Ludovic_Court=C3=A8s?= Content-Type: multipart/alternative; boundary="0000000000007a51f905d3a5eda1" X-Host-Lookup-Failed: Reverse DNS lookup failed for 2607:f8b0:4864:20::630 (failed) Received-SPF: none client-ip=2607:f8b0:4864:20::630; envelope-from=blake@sweatshoppe.org; helo=mail-pl1-x630.google.com X-Spam_score_int: -10 X-Spam_score: -1.1 X-Spam_bar: - X-Spam_report: (-1.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RDNS_NONE=0.793, SPF_HELO_NONE=0.001, SPF_NONE=0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-Mailman-Approved-At: Tue, 21 Dec 2021 09:19:11 -0500 X-BeenThere: guix-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Guix Devel , jgart Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: "Guix-devel" X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1640096399; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=Q+cX7ZcHaQfwYFrskEYw2rty0+eq0ZcarGGDGw6L4Vw=; b=cQaBauJYWV33wTJQ5dheNz2fti2gPhqzrbg9oRkA+jn7QWj3/o8fjNpDDPNWq96Q+1oPXN R30Eg9ESLRYrV/aIBIYVm/MrsJh7Djd/krH8IwK8Pvs/hxvXqaKe35YAp/6ZFLbhTryfBh PbhRBm10/EddXmAu6Z76mevvVrKsGl+CoyfcGhiiLdS3nuIemLElDI5wlJX/gGuFfVFQoP bw73VmcYcAyfvwoKpeA4vWCS4nroExJ5cWJX6eQcwSPW1GpLQpaw6GxfygFYa510JXipwy bIbEWWjTsl3xAOAOLOYW8DDe+FcXS4Apam5Pnan+VQjNOQ5kuBnNneP+i+xb1g== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1640096399; a=rsa-sha256; cv=none; b=apl6qV7VRem+RGZfYPlVSPjSpokJq1pxvtbnOv/wOwBwRu8gGDbslJ81O4yPWYfuecWq7t yfcjHXlgRPn0ybnk8rUhIXMjlbj0+2zyTb7B5kL6uXy/rOlTwz9H2OLs6NacEwOrKyI+A4 sR+vtpjtDeH5T0pvVtr3gXM8ccwLwnhBfh9WI0CwpQceLGFuhb6v4BpgHCTJVaA0Jx4sTS Mcswc8a6dgL991lGjpkCYbwmCVBzDsDEe6/V8iIqRjKi8G8jh+Ty5jWZtv96q7vwq0QB08 JI479bMM4gwHOrqguN/LUFAuoUvh6rRJhb6PS/a7nyZELlIR+UGXL5Ui93mcoQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=sweatshoppe-org.20210112.gappssmtp.com header.s=20210112 header.b=FGtBIcDI; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -2.33 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=sweatshoppe-org.20210112.gappssmtp.com header.s=20210112 header.b=FGtBIcDI; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: AB31435442 X-Spam-Score: -2.33 X-Migadu-Scanner: scn0.migadu.com X-TUID: Bj043oyECpor --0000000000007a51f905d3a5eda1 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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=C3=A8s wrote: > Hi Blake, > > Blake Shaw skribis: > > > While I've come to love Guile, compared to my experience with Racket it= s > > been quite burdensome for me to get in the hang of, something I attribu= te > > 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 th= e > > 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=E2=80=99t take th= e 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=E2=80=99s take advantage of that! > > Thanks, > Ludo=E2=80=99. > > --0000000000007a51f905d3a5eda1 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi Ludo,

(re= plying to this email from my other email address because I can't seem t= o 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 hopef= ully 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 w= ill offer solutions that if everyone agrees to I'll go ahead and start = putting to work.=C2=A0

E= z,
Blake=C2=A0

On Tue, Dec 21, 2021, 01:57 Ludo= vic Court=C3=A8s <ludo@gnu.org> w= rote:
Hi Blake,

Blake Shaw <blake@nonconstructivism.com> skribis:

> While I've come to love Guile, compared to my experience with Rack= et its
> been quite burdensome for me to get in the hang of, something I attrib= ute
> 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 equiv= alent
> in Racket, but a lack of consistency in the path that leads there in t= he
> 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=E2=80=99t 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=E2=80=99s take advantage of that!

Thanks,
Ludo=E2=80=99.

--0000000000007a51f905d3a5eda1--