Re: Guix cookbook (was: guile scheme tutorial)

[Ricardo Wurmus]

Pierre Neidhardt  writes:

> I agree with all your points!
>
> Regarding the bootstrapping process: we could already split the
> packaging tutorial into 2 "recipes":
> - A guile primer
> - The actual packaging tutorial
>
> Of course we would interlink them.
>
> Once done, we should not forget to update the blog post to let the
> readers know to refer to the corresponding cookbook instead.

Sounds good.  I’d like to keep the cookbook chapters rather short and
focused, so splitting things up into independent chapters is fine.

> Out of curiosity, can you remember which part of the tutorial is out of
> date?  I cannot think of anything.

I think it was a misunderstanding:

http://bayfront.guix.info:/2019-05-08.log#042356

The tutorial says:

Follow the instruction from the "Contributing" chapter in the manual
to set up the repository environment.

I think they did not follow those instructions.  Sorry for the false
alarm!

--
Ricardo

Guix cookbook (was: guile scheme tutorial)

[Ricardo Wurmus]

Pierre Neidhardt  writes:

> A well written manual might not be the only answer we are looking for.  How
> do we teach complex concepts in schools?  With examples and exercises.
> Maybe we should do that.  Blog articles could be a good fit.

I’m not a fan of blog posts for teaching, because they quickly lose
relevance.  An example: recently someone on IRC said they were following
your packaging tutorial and something wasn’t working; someone else then
said that the blog post was outdated.  I don’t recall the details, but I
find this worrying, because people might spend time learning something
from blog posts only to have to unlearn things again.

Blog posts are great for outreach and to spawn contemporary discussions.
But I think that ultimately we should enhance the manual.  We are not
limited to having just one document that needs to meet all
requirements.  We can have more than one thing.

Previously, we floated the idea of having a Guix cookbook with short
tutorials showing how to achieve well-defined tasks such as writing a
package (i.e. an updated and distilled version of your blog post
perhaps), setting up a bluetooth-enabled MPD-powered media workstation,
configuring a complex web application with database, web server, etc.

I’d really like to see such a cookbook become part of Guix.  It would
always be up-to-date and it can provide much needed examples that might
otherwise clutter up the manual.

What do you think?  Shall we start with converting your packaging
tutorial?

--
Ricardo