On 2/12/22 18:32, Eli Zaretskii wrote:
From: Ricardo Wurmus <rek...@elephly.net>
Date: Sat, 12 Feb 2022 14:49:20 +0100
Cc: guile-user@gnu.org
The argument of lack of examples in the Guile/Guix documentation has
been made several times now, or at least, I've seen it being made
several times
The Guix documentation contains examples, but it’s already very long and
intimidating, so we started the Cookbook for more extensive tutorials
and examples.
It hasn’t seen as much uptake by contributors as I hoped, but it’s there
and can be extended with more examples, big and small.
I don't think just adding examples will cut it, although it will
certainly help.
Only adding examples might not be enough, but definitely a huge step forward. In
whatever form they appear, a separate Cookbook, or whatever. The number of
times, I have sat in front of the reference manual and needed to try things out,
in order to figure out how to make use of something in the manual is high.
Examples would surely be a very beginner friendly thing to do.
My take of the issue is that the Guile reference manual is little more
than the collection of the doc strings of the various Guile APIs. The
doc strings are by their very nature quite terse and lack the "glue":
the text which will explain the relative merits and demerits of each
API wrt the other, the factors to consider when deciding which APIs to
use, etc. It also doesn't make it easy to have helpful
cross-references. Moreover, adding examples to the doc strings will
have a disadvantage: it will increase the memory footprint of running
Guile applications.
Which is why I think the effort should be in the direction of
extending the parts of the manual that aren't produced from the doc
strings, but instead are written by humans to help other humans.
Best regards,
Zelphir
--
repositories: https://notabug.org/ZelphirKaltstahl
