From mboxrd@z Thu Jan 1 00:00:00 1970 From: Bengt Richter Subject: Re: Reworking the cookbook layout Date: Wed, 27 Nov 2019 16:43:50 -0800 Message-ID: <20191128004350.GA1076@PhantoNv4ArchGx.localdomain> References: <20191126231136.212ff31e@sybil.lepiller.eu> Reply-To: Bengt Richter Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Return-path: Received: from eggs.gnu.org ([2001:470:142:3::10]:55547) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ia7uk-0005VY-Pb for guix-devel@gnu.org; Wed, 27 Nov 2019 19:44:13 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ia7ui-0001Zu-TH for guix-devel@gnu.org; Wed, 27 Nov 2019 19:44:10 -0500 Received: from imta-36.everyone.net ([216.200.145.36]:55808 helo=imta-38.everyone.net) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1ia7ui-0001Ti-Ac for guix-devel@gnu.org; Wed, 27 Nov 2019 19:44:08 -0500 Content-Disposition: inline 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 On +2019-11-27 12:08:00 +0100, zimoun wrote: > 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". > To my mind, it's a matter of the scope of your goal: how-to: a cache of narrowly useful knowledge, usually in a form of code snippets or step-by-step work flow guidance. I really like the example set by "info giteveryday" or "git help everyday" (the former being more navigable, the latter leads to a man page on my system) Handy one-liners that you could re-invent, but don't remember for sure, and don't want to re-debug belong in a how-to, as I see it. tutorial: a guide towards mastery of a tool _set_, not just a specific use of a specific tool. Usually starts with an introduction to basics, but can go anywhere and all over. E.g. emacs's opening page invites you to an example (and tells you how to turn that prompt off when you are ready to do without). Likewise info has a tutorial. An important aspect is being able to find and extract what you want easily and put it to use where you want to. That's not a matter of _what_ you put in how-tos or tutorials, but how easily it can be found and used. emacs is generally great at that, especially having guix and guile info in buffers that you can copy snippets from, and a shell session likewise. Though I will say communication between emacs under X and emacs in the login (non-gui) console is not smooth for me -- probably because I haven't searched enough for how others may have created a solution. Maybe "M-x archive-buffers .. to .. FILE" which console emacs could "Mx load-buffers .. from .. FILE" -- which is easier, to hack or to find? ;-/ (Actually I think we ought to have a clipboard daemon completely independent of X and any app, secure and ACL-controlled, something like IPC for QubesOS). My solution long ago was a bash script called stack, which uses dd to append anything piped to it to the end of an internal file, while logging the byte length to a metafile, or writing to stdout the last segment written if nothing is on stdin, and optionally trimming it back off if -pop option. Easy to use from either bash by piping a region to it or inserting the result of its execution ( "C-u Esc ! stack" or "C-u Esc ! stack -pop ). Why go on about seemingly off-topic tools? Well, to me, my little helper tools are important. Probably most hackers have a set of their own. My point here is that I think guix can provide a nice way to share not only how-to tips and tutorials etc, but also helper tools to enhance the hacking environment. AND: that tools and docs should be designed with their interaction in mind. E.g., delimiting things for easy extraction for various purposes. IMO it would be nice if ANY app that presents text had a way to select a region and hit a pipe key that would prompt for a shell command to pipe it to, like emacs. But why not info by itself, or man -- or less for that matter. And not dependent on X. > 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? > See above, but takeaway is think about the hacker work environment so that docs work well with unix-philosophy helper tools that can be shared simply without waiting for some big update. -- Regards, Bengt Richter