Re: timestamp

[Eli Zaretskii <eliz@gnu.org>]

> 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.

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.