Re: Planet of Guix-related posts?

[Oliver Propst]

As someone how cares deeply about Guix I can state I think that the 
Cookbook is a great resource.


I feels like the Cookbook have a clear focus on quality documentation 
and has to life only as a result of lots hard work and love for the Guix 
project. That said even as a technical person I do must admit that find 
some segment and concepts in the cookbook as hard to read and understand 
(especially from the the perspective of a non-technical person). So 
guess a relevant question could be how do we make the Guix documentation 
easier to understand for everybody and how do we improve the 
explanations of the current segments in the Cookbook.



--
Kinds regards Oliver Propst
https://twitter.com/Opropst

Re: Planet of Guix-related posts?

[Ricardo Wurmus]

Matt  writes:

> What problem is the cookbook trying to
> solve? Once that's clear, we can make judgements about whether it
> accomplishes that goal.

The idea of a cookbook arose from dissatisfaction with the manual.  The
manual had few examples, and as a reference style document it was
considered to be the wrong place for long excursions, tutorials, and
detailed examples.

I started the cookbook by adapting some popular blog posts.  The idea
was that it could be home to hands-on tutorials, motivated examples,
hints and tricks, etc that would be out of place in the manual.

This is not set in stone, and it was always the intention to let the
cookbook become whatever contributors made of it.  It was only always
meant to enhance and supplement the manual.

-- 
Ricardo

Re: Planet of Guix-related posts?

[Ricardo Wurmus]

Matt  writes:

>   On Mon, 10 Jan 2022 10:21:51 -0500 zimoun  
> wrote 
>
>  > (On a side note between parenthesis, we should avoid to fall into the
>  > "Package Definition" tutorial fallacy; as explained here for monads
>  > 
> https://byorgey.wordpress.com/2009/01/12/abstraction-intuition-and-the-monad-tutorial-fallacy/.
>  > And I wrote one post about monad and another about Packaging. ;-)
>  > However, I think the official documentation has enough materials for
>  > starting to package. End of parenthesis.)
>
> If many people feel inclined to write their own packaging tutorial,
> it's probably an indication that the manual isn't sufficient.

The experience with monad tutorial suggests that people write them
because they learned something new and want to put their understanding
into words in the hopes that other people benefit from it.

There is an overabundance of monad tutorials out there.  This is not
evidence of the claim that existing explanations are somehow flawed.

-- 
Ricardo

Re: Planet of Guix-related posts?

[André A . Gomes]

Matt  writes:

>   On Mon, 10 Jan 2022 10:21:51 -0500 zimoun  
> wrote 
>
>  > (On a side note between parenthesis, we should avoid to fall into the
>  > "Package Definition" tutorial fallacy; as explained here for monads
>  > 
> https://byorgey.wordpress.com/2009/01/12/abstraction-intuition-and-the-monad-tutorial-fallacy/.
>  > And I wrote one post about monad and another about Packaging. ;-)
>  > However, I think the official documentation has enough materials for
>  > starting to package. End of parenthesis.)
>
> If many people feel inclined to write their own packaging tutorial,
> it's probably an indication that the manual isn't sufficient.  I would
> urge you and others to not fall into the "don't touch it because it's
> good enough for me fallacy".  Others may, and probably do, see things
> differently.

I'd say it indicates that everyone has their own way of assimilating
ideas.  Often times we map things in our minds by means of
simplifications, abuses of languages, imprecisions, etc.


-- 
André A. Gomes
"Free Thought, Free World"

Re: Planet of Guix-related posts?

[Matt]

  On Mon, 10 Jan 2022 10:21:51 -0500 zimoun  
wrote 

 > (On a side note between parenthesis, we should avoid to fall into the
 > "Package Definition" tutorial fallacy; as explained here for monads
 > https://byorgey.wordpress.com/2009/01/12/abstraction-intuition-and-the-monad-tutorial-fallacy/.
 > And I wrote one post about monad and another about Packaging. ;-)
 > However, I think the official documentation has enough materials for
 > starting to package. End of parenthesis.)

If many people feel inclined to write their own packaging tutorial, it's 
probably an indication that the manual isn't sufficient.  I would urge you and 
others to not fall into the "don't touch it because it's good enough for me 
fallacy".  Others may, and probably do, see things differently.  

This is where I should say precisely what I think is unclear. Only that way can 
we find what the source of confusion is and maybe address it in the 
documentation.  I can't do that now, but the documentation meeting might be a 
good place for that.

 > Last, we have to distinguish between "temporary" content and
 > well-maintained documentation.  We discussed many times the Cookbook
 > and I think what we are trying with a limited success that this
 > document fits too much goals at the same time.  For instance, if I
 > would have to send a patch for fixing Wikipedia typo or adding a quick
 > paragraph about preconditioner of linear system, I would never just do
 > one or the other.  The Cookbook is currently too rigid for quick
 > half-backed recipes.

This is a good observation. What problem is the cookbook trying to solve? Once 
that's clear, we can make judgements about whether it accomplishes that goal.

Re: Planet of Guix-related posts?

[Matt]

 > Hi,
 > 
 > My two points are:
 > 
 >  1. we could have a Guix planet -- we should avoid the cathedral for
 > quick recipes
 >  2. too many different goals are directed to the Cookbook
 > 
 > 
 > Well, my point is: instead of cathedral with an authority accepting
 > patches after review, why not a web syndication (bazaar) as a Planet
 > collecting various blogs.  This would help to stay aware.  For
 > instance, I read,
 > 
 > https://planet.haskell.org/
 > https://ocaml.org/community/planet/
 > https://planet.emacslife.com/
 > https://planet.scheme.org/
 > 
 > and many others and for Guix-related, basically, I use Ludo's toots as
 > such Planet.  Thanks Ludo. ;-)
 > 
 > Bah, I do not know if many blogs about Guix are around and how
 > frequently they would be updated.
 > 
 > Similarly, some time ago, an "awesome list" had been started and now,
 > quickly searching, I find 2:
 > 
 > https://github.com/techenthusiastsorg/awesome-guix
 > https://sr.ht/~lle-bout/awesome-guix/
 > 
 > Therefore, doing so...
 > 
 > On Sat, 8 Jan 2022 at 17:25, Matt  wrote:
 > 
 > > I have two documents written in Org:
 > > 1. http://excalamus.com/test-guix-case-study-plover-python-dictionary.html
 > 
 > (On a side note between parenthesis, we should avoid to fall into the
 > "Package Definition" tutorial fallacy; as explained here for monads
 > https://byorgey.wordpress.com/2009/01/12/abstraction-intuition-and-the-monad-tutorial-fallacy/.
 > And I wrote one post about monad and another about Packaging. ;-)
 > However, I think the official documentation has enough materials for
 > starting to package. End of parenthesis.)
 > 
 > 
 > > 2. http://excalamus.com/2021-10-06-guix-debug.html
 > 
 > ...it is possible to individually write using our preferred tools and
 > managed our way.
 > 
 >  Moreover, for instance, times to times, I write entries to my "blog":
 > 
 > https://simon.tournier.info/posts/
 > 
 > For example, this edited
 > 
 > had been published before there
 > .
 > 
 > Therefore, maybe people not afraid to write to their own blog but
 > afraid (or not knowing how to) to submit patches would provide
 > material for the official blog post, who knows. :-)
 > 
 > 
 > Last, we have to distinguish between "temporary" content and
 > well-maintained documentation.  We discussed many times the Cookbook
 > and I think what we are trying with a limited success that this
 > document fits too much goals at the same time.  For instance, if I
 > would have to send a patch for fixing Wikipedia typo or adding a quick
 > paragraph about preconditioner of linear system, I would never just do
 > one or the other.  The Cookbook is currently too rigid for quick
 > half-backed recipes.
 > 
 > In my views, for what they are worth, I think the level of
 > documentation should be:
 > 
 >  - manual as it is now
 >  - cookbook turned into a step by step comprehensive tutorial
 >  - wiki being a how-to-quickly-fix, similar to Arch wiki for instance
 > 
 > We have Guix manual which is really great.  We have Guile manual which
 > is really great once you know what you want.  What is missing in a
 > document in the middle and something similar to a wiki where it is
 > easy to edit and change.
 > 
 > For what the analogy is worth, Emacs manual and Emacs Lisp manual are
 > doing their job as manual.  However, if one is new to programming, the
 > document An Introduction to Programming in Emacs Lisp [1] is a great
 > resource because it is in the middle, IMHO.  The Cookbook should act
 > similarly.  Something as an official kind-of tutorial.
 > 
 > 1: https://www.gnu.org/software/emacs/manual/eintr.html
 > 
 > And somewhere an easy to edit half-maintained not-really reviewed wiki
 > where anyone could provide their material.

+1

Documentation is fundamentally about teaching. Having different avenues is 
needed to help structure learning. I think using Emacs as a model here is a 
great idea.

Planet of Guix-related posts?

[zimoun]

Hi,

My two points are:

 1. we could have a Guix planet -- we should avoid the cathedral for
quick recipes
 2. too many different goals are directed to the Cookbook


Well, my point is: instead of cathedral with an authority accepting
patches after review, why not a web syndication (bazaar) as a Planet
collecting various blogs.  This would help to stay aware.  For
instance, I read,

https://planet.haskell.org/
https://ocaml.org/community/planet/
https://planet.emacslife.com/
https://planet.scheme.org/

and many others and for Guix-related, basically, I use Ludo's toots as
such Planet.  Thanks Ludo. ;-)

Bah, I do not know if many blogs about Guix are around and how
frequently they would be updated.

Similarly, some time ago, an "awesome list" had been started and now,
quickly searching, I find 2:

https://github.com/techenthusiastsorg/awesome-guix
https://sr.ht/~lle-bout/awesome-guix/

Therefore, doing so...

On Sat, 8 Jan 2022 at 17:25, Matt  wrote:

> I have two documents written in Org:
> 1. http://excalamus.com/test-guix-case-study-plover-python-dictionary.html

(On a side note between parenthesis, we should avoid to fall into the
"Package Definition" tutorial fallacy; as explained here for monads
https://byorgey.wordpress.com/2009/01/12/abstraction-intuition-and-the-monad-tutorial-fallacy/.
And I wrote one post about monad and another about Packaging. ;-)
However, I think the official documentation has enough materials for
starting to package. End of parenthesis.)


> 2. http://excalamus.com/2021-10-06-guix-debug.html

...it is possible to individually write using our preferred tools and
managed our way.

 Moreover, for instance, times to times, I write entries to my "blog":

https://simon.tournier.info/posts/

For example, this edited

had been published before there
.

Therefore, maybe people not afraid to write to their own blog but
afraid (or not knowing how to) to submit patches would provide
material for the official blog post, who knows. :-)


Last, we have to distinguish between "temporary" content and
well-maintained documentation.  We discussed many times the Cookbook
and I think what we are trying with a limited success that this
document fits too much goals at the same time.  For instance, if I
would have to send a patch for fixing Wikipedia typo or adding a quick
paragraph about preconditioner of linear system, I would never just do
one or the other.  The Cookbook is currently too rigid for quick
half-backed recipes.

In my views, for what they are worth, I think the level of
documentation should be:

 - manual as it is now
 - cookbook turned into a step by step comprehensive tutorial
 - wiki being a how-to-quickly-fix, similar to Arch wiki for instance

We have Guix manual which is really great.  We have Guile manual which
is really great once you know what you want.  What is missing in a
document in the middle and something similar to a wiki where it is
easy to edit and change.

For what the analogy is worth, Emacs manual and Emacs Lisp manual are
doing their job as manual.  However, if one is new to programming, the
document An Introduction to Programming in Emacs Lisp [1] is a great
resource because it is in the middle, IMHO.  The Cookbook should act
similarly.  Something as an official kind-of tutorial.

1: https://www.gnu.org/software/emacs/manual/eintr.html

And somewhere an easy to edit half-maintained not-really reviewed wiki
where anyone could provide their material.


Cheers,
simon