Reworking the cookbook layout

[Julien Lepiller]

Hi Guix!

Today I have been reading https://www.divio.com/blog/documentation/
which makes some good points on how to write good documentation. They
suggest to divide documentation into four categories, depending on
their purpose:

- tutorials, written for newcomers. They should be to the point and
  guide a new user through every step of using the new system.
- how-tos. They should be "goal-oriented" and allow
  a user who knows what they want to do, to learn how to do it.
- explanations. They are more theoretical and should give more
  knowledge on how it all works.
- reference. It should contain all the technical details of the code.

Following these principles, I propose the attached patch, that changes
the layout a bit. Instead of grouping articles by topic, I suggest
grouping them by one of the first three categories above (the guix
manual is the reference, and it's excellent, so we don't need a
reference documentation in the cookbook).

First, we have tutorials.  We are missing a few things, but I imagine
the following structure: start with a tutorial on guix, the package
manager (helping a newcomer installing guix on a foreign distribution
and taking their first steps with guix: install, remove, pull, upgrade).
Then, we would propose the user to continue reading the tutorial on
installing the guix system, or the guides on more advanced topics in
package management. Then, a tutorial on the guix system will help the
user install and understand the basic concepts of the system, for
instance by installing it first in a virtual machine, then guiding them
through their first install using the graphical installer. At the end,
we would recommend them to continue with the scheme tutorial, because
their configuration is actually a scheme file, and they could get more
power by learning scheme. Or they could continue on to the guides on
how to configure specific things. Then the scheme tutorial and the
packaging tutorial we already have.

The second part of the cookbook would be a bunch of how-tos, this time
grouped by target audience (almost topics): package manager users,
system users and packagers. That's where we would have things like "how
to reproduce a scientific paper", "how to develop a software using
guix", "how to configure my locales", "how to install on Android", "how
to install the system on an ARM board", etc. I think this will be the
biggest part of the cookbook, so I propose to directly have three
chapters for it instead of one with three parts.

The last part would be some discussions on how Guix works, what it is.
This is currently empty, but I think it would make sense to discuss
what a profile is, show how profile generations are symlinks, how the
gc works, why the store is read-only, what is the relation between Guix
and Docker (a recent discussion on the list), why does "guix pull"
create a separate profile, and so on.

I think having such a plan will also help us see what is missing and
how to improve the cookbook concretely. Does it make sense?

0001-doc-cookbook-Rework-layout.patch
Description: Text Data