Re: Reworking the cookbook layout

[Julien Lepiller]

Le 27 novembre 2019 16:26:06 GMT+01:00, zimoun <address@hidden> a écrit :
>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.

I'd say even a search form :)

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

So if I understand correctly, the cookbook would be an unordered collection of 
articles from many people. I'd say pretty intimidating.

What I was proposing was to add more structure and a more logical progression, 
from introductory examples to more advanced use-cases. I didn't suggest that 
information should not be duplicated (although references to other sections are 
fine too). My goal is to have a document that can help people along the way 
from being interested in guix to becoming a contributor or an advanced user. 
More of a manual or a book.

Maybe we need a separate document from the cookbook for that purpose. I'd like 
to have a structured documentation on guix aimed at users, rather than an 
unstructured collection of stories from users. Does it make sense?

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

In the structure I propose, it would be the last part of the packaging 
tutorial, or a tutorial on its own, advertised after the packaging tutorial.

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

I'd say, you can learn to cook from a cookbook, but a chef has more of a formal 
training :) I think that's what I'd like to do.

>
>
>Cheers,
>simon