Re: Reworking the cookbook layout

[Julien Lepiller]

Le 27 novembre 2019 12:08:00 GMT+01:00, zimoun <address@hidden> a écrit :
>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. :-)

So, following the structure I propose, the cookbook would only contain 
tutorials and how-tos. Then we would need another place for deeper explanations.

>
>
>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".

A tutorial does not have a particular goal other than giving a tour of the 
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.

>
>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 packager, 
so I don't need a tutorial on packaging or scheme. I could still learn 
something, but I'll skip most of this document. I think it's best to split it 
for different readers: a tutorial, how-tos for some difficult points that can 
arrise and explanations of the packaging architecture for instance.

>
>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.

Right, but we're not writing a lot either way… I think a clearer editorial 
policy will help us see what's needed and bring in more contributions.

>
>
>> 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.).

Maybe the name "tutorial" is not good enough to express what I mean. It's 
supposed to give you some precise steps you have to follow to get more familiar 
with a tool when you discover it for the first time. Discussing docker doesn't 
give you any practice with Guix, only theoretical knowledge. It's for a 
different audience.

>
>
>What do you think?
>
>
>All the best,
>simon