Re: Reworking the cookbook layout

[Bengt Richter]

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 <address@hidden> 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