From mboxrd@z Thu Jan 1 00:00:00 1970 From: Julien Lepiller Subject: Re: Reworking the cookbook layout Date: Wed, 27 Nov 2019 13:14:27 +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]:53147) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iZwDU-00060L-Gl for guix-devel@gnu.org; Wed, 27 Nov 2019 07:14:46 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iZwDR-0004R1-SC for guix-devel@gnu.org; Wed, 27 Nov 2019 07:14:44 -0500 Received: from lepiller.eu ([2a00:5884:8208::1]:36146) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1iZwDR-0004Pf-9A for guix-devel@gnu.org; Wed, 27 Nov 2019 07:14:41 -0500 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: zimoun Cc: Guix Devel Le 27 novembre 2019 12:08:00 GMT+01:00, zimoun a =C3=A9crit : >Hi, > >Thank you to open the discussion about the Cookbook=2E > >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=2E > >Currently, it is all what cannot be included in the Reference Manual=2E >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=2E I am mean the one of my Grand-Mother is not=2E :-) So, following the structure I propose, the cookbook would only contain tut= orials and how-tos=2E Then we would need another place for deeper explanati= ons=2E > > >On Tue, 26 Nov 2019 at 23:12, Julien Lepiller >wrote: > >> Today I have been reading https://www=2Edivio=2Ecom/blog/documentation/ >> which makes some good points on how to write good documentation=2E 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)=2E > >[1] https://developers=2Egoogle=2Ecom/season-of-docs > > >> - tutorials, written for newcomers=2E They should be to the point and >> guide a new user through every step of using the new system=2E >> - how-tos=2E They should be "goal-oriented" and allow >> a user who knows what they want to do, to learn how to do it=2E >> - explanations=2E They are more theoretical and should give more >> knowledge on how it all works=2E >> - reference=2E It should contain all the technical details of the code= =2E > >To me this structure is nice but too strong=2E I do not see what is the >difference between "how-tos" and "tutorials"=2E A tutorial does not have a particular goal other than giving a tour of the= tools and main functionalities=2E So it's more a what-is than a how-to=2E = Not how to program in scheme, but what is it like to program in scheme=2E > >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=2E) > >So I feel an arbitrary boundary=2E I think it's not too nice to mix all of this together: I'm already a packa= ger, so I don't need a tutorial on packaging or scheme=2E I could still lea= rn something, but I'll skip most of this document=2E I think it's best to s= plit it for different readers: a tutorial, how-tos for some difficult point= s that can arrise and explanations of the packaging architecture for instan= ce=2E > >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=2E Right, but we're not writing a lot either way=E2=80=A6 I think a clearer e= ditorial policy will help us see what's needed and bring in more contributi= ons=2E > > >> Following these principles, I propose the attached patch, that >changes >> the layout a bit=2E 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)=2E > >I propose to group in 2 categories: > > - How To / Tutorial > - Blog post > >And the both can overlap=2E 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"=2E > >The issue is that the Blog part could not be synchronise=2E But let warn >the reader and to me it is not an issue=2E The Blog part can be amended >when something wrong is reported=2E > >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=2E)=2E Maybe the name "tutorial" is not good enough to express what I mean=2E It'= s supposed to give you some precise steps you have to follow to get more fa= miliar with a tool when you discover it for the first time=2E Discussing do= cker doesn't give you any practice with Guix, only theoretical knowledge=2E= It's for a different audience=2E > > >What do you think? > > >All the best, >simon