Re: Reworking the cookbook layout

[zimoun]

Hi,

Thank you to open the discussion about the Cookbook.

The first thing is: what is the purpose of the Cookbook? I mean I am
not sure we all define the same object with the same goal.

Currently, it is all what cannot be included in the Reference Manual.
So do we need to organize all this material with an strong hierarchy?
A cookbook is a collection of recipes and it not generally well
organized. I am mean the one of my Grand-Mother is not. :-)


On Tue, 26 Nov 2019 at 23:12, Julien Lepiller <address@hidden> wrote:

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

I was reading similar elsewhere with the idea to prepare what we could
propose for the next round of the Google Seasons of Doc [1] (if any).

[1] https://developers.google.com/season-of-docs


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

To me this structure is nice but too strong. I do not see what is the
difference between "how-tos" and "tutorials".

And for example, the blog "Packaging" entry is in the same time:

 - a tutorial because it is written for newcomers
 - "goal-oriented" because it explains "how to package"
 - explicative because it provides how it all works (scheme explanations, etc.)

So I feel an arbitrary boundary.

Then it is some work to revamp the blog entries and we should reduce
the workload because when we are revamping we are not writing other
materials.


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

I propose to group in 2 categories:

 - How To / Tutorial
 - Blog post

And the both can overlap. I mean it is not an issue that a blog post
entry explains Scheme for the beginners and in the time there is an
entry "My first steps with Scheme" in the "How To/Tutorial".

The issue is that the Blog part could not be synchronise. But let warn
the reader and to me it is not an issue. The Blog part can be amended
when something wrong is reported.

Concerning deeper explanations (for example relationship between
Docker and Guix), I consider that as a "tutorial": a method of
transferring knowledge (wikipedia) or the tutor teaches/discusses
particular point (Collins dic.).


What do you think?


All the best,
simon