From mboxrd@z Thu Jan 1 00:00:00 1970 From: zimoun Subject: Re: Reworking the cookbook layout Date: Wed, 27 Nov 2019 16:26:06 +0100 Message-ID: References: <20191126231136.212ff31e@sybil.lepiller.eu> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:470:142:3::10]:50581) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iZzCu-0006up-F6 for guix-devel@gnu.org; Wed, 27 Nov 2019 10:26:22 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iZzCs-0004p6-LM for guix-devel@gnu.org; Wed, 27 Nov 2019 10:26:20 -0500 Received: from mail-qk1-x733.google.com ([2607:f8b0:4864:20::733]:46541) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iZzCs-0004ns-Gy for guix-devel@gnu.org; Wed, 27 Nov 2019 10:26:18 -0500 Received: by mail-qk1-x733.google.com with SMTP id f5so1458765qkm.13 for ; Wed, 27 Nov 2019 07:26:18 -0800 (PST) In-Reply-To: List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: Julien Lepiller Cc: Guix Devel I break the usual rules of reply. Hope that will be ok. :-) On Wed, 27 Nov 2019 at 13:14, Julien Lepiller wrote: > Le 27 novembre 2019 12:08:00 GMT+01:00, zimoun = a =C3=A9crit : > >On Tue, 26 Nov 2019 at 23:12, Julien Lepiller > >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 tu= torials and how-tos. Then we would need another place for deeper explanatio= ns. [...] > >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 a= nd 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 th= e 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 pack= ager, so I don't need a tutorial on packaging or scheme. I could still lear= n something, but I'll skip most of this document. I think it's best to spli= t it for different readers: a tutorial, how-tos for some difficult points t= hat 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=E2=80=A6 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