> 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 <m...@excalamus.com> 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 > <http://hpc.guix.info/blog/2021/10/when-docker-images-become-fixed-point/> > had been published before there > <https://simon.tournier.info/posts/2021-09-17-guix-pack-docker.html>. > > 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.
