Re: Examples in Guile documentation

[Zelphir Kaltstahl <zelphirkaltstahl@posteo.de>]

On 2/12/22 18:32, Eli Zaretskii wrote:
>> From: Ricardo Wurmus <rekado@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