Re: Reworking the cookbook layout

[zimoun]

I break the usual rules of reply. Hope that will be ok. :-)


On Wed, 27 Nov 2019 at 13:14, Julien Lepiller <address@hidden> wrote:

> Le 27 novembre 2019 12:08:00 GMT+01:00, zimoun <address@hidden> a écrit :

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


> >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. :-)
>
> So, following the structure I propose, the cookbook would only contain 
> tutorials and how-tos. Then we would need another place for deeper 
> explanations.

[...]

> >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.
>
> [...] I think a clearer editorial policy will help us see what's needed and 
> bring in more contributions.

I agree that a clearer editorial policy will help us.

It is what I am trying to point too. :-)

However, I disagree on the structure you propose because I find it too
strong, with too much boundary.


> >To me this structure is nice but too strong. I do not see what is the
> >difference between "how-tos" and "tutorials".
>
> A tutorial does not have a particular goal other than giving a tour of the 
> tools and main functionalities. So it's more a what-is than a how-to. Not how 
> to program in scheme, but what is it like to program in scheme.

To me, it is too arbitrary.

Non-related example, but maybe it underlines my point. Recently, I
discovered that we can generate Docker images on foreign distro using
"guix system docker-image". But because of the structure, I have never
carefully read the section "System Configuration". I have always
thought that this section was about "Guix System" and I am not
currently using it. Well, I am not saying that the Reference Manual is
doomed; in this case, I am too lazy to correctly search. And for sure,
we have to put somewhere somestuff.

My point is: what naturally makes sense to you does not necessary make
sense to me, and vice-versa. And decide if this or that belongs to
that or this is often arbitrary. That's why I think the structure
needs only 2 levels and a good index.


> >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.
>
> I think it's not too nice to mix all of this together: I'm already a 
> packager, so I don't need a tutorial on packaging or scheme. I could still 
> learn something, but I'll skip most of this document. I think it's best to 
> split it for different readers: a tutorial, how-tos for some difficult points 
> that can arrise and explanations of the packaging architecture for instance.

In my (real) cookbook, I have 2 different recipes of the same meal
(say galette [sarrasin] ;-)).
And they are not written on pages close to each selfes but contrary
one is on the beginning of the cookbook, the other at the end.
One comes from a friend -- student time.
One comes from a guest -- couch surfing or related.
Now, I could write my own recipe, kind of adaptation of the two
previous ones. However, my sister find easier the first one and my dad
the last one. See what I mean? :-) It depends on the flavour, how you
read, etc.

Well, we disagree on what should be the Cookbook because it lacks a
clear editorial policy. ;-)
Are not we trying to define one right now? :-)

To me, the cookbook is a collection of recipes. And different recipes
can overlap. To me, a recipe is a story about a topic; the same
explanations can be detailed twice if they are important to the story.
And because they are worded differently, Alice will prefer the story 1
and Bob the 2. Some story can be short, other lengthy. One key point
is a good index: an index where a "concept" that points to several
entries.


> > Right, but we're not writing a lot either way…

Yes! I agree. Because 1. it is relatively new 2. it is hard to know
what is the editorial policy (aim of the cookbook) so 3. the blog post
has been revamped.

For example, I have a draft (needs a lot of polishing) about "My first
steps to contribute" and I do not know what to do with.



I am happy that you have opened the discussion. And I think that
writing a recipe should be a good way to attract new contributors.



Cheers,
simon