From mboxrd@z Thu Jan 1 00:00:00 1970 From: zimoun Subject: Re: Reworking the cookbook layout Date: Wed, 27 Nov 2019 12:08:00 +0100 Message-ID: References: <20191126231136.212ff31e@sybil.lepiller.eu> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Return-path: Received: from eggs.gnu.org ([2001:470:142:3::10]:39902) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iZvB7-0002uS-9N for guix-devel@gnu.org; Wed, 27 Nov 2019 06:08:14 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iZvB5-000619-Ta for guix-devel@gnu.org; Wed, 27 Nov 2019 06:08:13 -0500 Received: from mail-qt1-x830.google.com ([2607:f8b0:4864:20::830]:40834) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iZvB5-00060s-Pj for guix-devel@gnu.org; Wed, 27 Nov 2019 06:08:11 -0500 Received: by mail-qt1-x830.google.com with SMTP id z22so4064307qto.7 for ; Wed, 27 Nov 2019 03:08:11 -0800 (PST) In-Reply-To: <20191126231136.212ff31e@sybil.lepiller.eu> 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 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 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