Subject: Re: bug#53827: [PATCH] Add a TLDR entry to the cookbook for building Guix from Git.

From: Pierre-Henry Fröhring <[email-masked]>
Date: Tue, 15 Feb 2022 11:10:24 +0100

Hello Ludovic,

I try to make Guix our default package manager.  It's really wonderful
so far.  To that end, I need TLDRs so that less experienced
developpers can get going /fast/.  Deeper understanding will come in
time.

I also need to convince that Guix is /easy/ to third parties.  I need
to /show/ that /installing/, /configuring/ and /using/ Guix is fast
and efficient.  I found out that TLDRs are great tools for that.

I need to have small TLDRs so that when things go wrong, it's easy to
know where and fix either the TLDR or the manual steps. Also,
sometimes, things go wrong and are not documented. /E.g./ setting
~LC_ALL=C.UTF-8~ will make Guix complain even after installing ~guix
install glibc-utf8-locales~.  I can factor this knowledge inside these
TLDR fast.

Now, if I compare the official documentation:

  https://guix.gnu.org/manual/devel/en/html_node/Building-from-Git.html

with the TLDR version of it:

https://transient.blog/1/tutoriel-guix-devel/ea10580e-9750-463a-aff4-9a3e90809ad4/54fcc4f606

Then, even after taking into account the great work accomplished in
the documentation, I find the TLDR version more convincing.

Pierre-Henry

On Tue, 2022-02-15 at 10:20 +0100, Ludovic Courtès wrote:
> Hi,
> 
> Maxime Devos <[email-masked]> skribis:
> 
> > Pierre-Henry Fröhring schreef op zo 06-02-2022 om 22:33 [+0100]:
> > > +@node Building from Git
> > > +@chapter Building from Git
> > > +
> > > +Build Guix from Git and start hacking.
> > > +
> > > +@node Context
> > > +@section Context
> > 
> > This is all explained in the main manual in more detail, can a
> > cross-
> > reference to ‘(guix)Building from Git’ be added?
> 
> Yes, I wonder: what do you think Pierre-Henry is wrong with the
> same-named section of the manual?
> 
>  
> https://guix.gnu.org/manual/devel/en/html_node/Building-from-Git.html
> 
> It is more verbose, but the important commands are in @example boxes,
> which should allow the reader to skip straight to the main parts.
> 
> WDYT?
> 
> Ludo’.