Re: Guix Documentation Meetup

Re: Guix Documentation Meetup

[calcium]

I strongly agree with matt about the importance of discoverability that is currently lacking (`geiser-doc-symbol-at-point isn't enough).
Its pretty hard to find out how to do something beyond the basic usage.

I would like for Guix to host a community wiki (in addition to a more discoverable official documentation).

Because a collaborative wiki that encourages effortless and low quality content could alleviate the problem of discoverability and context.

This could serve as a stepping stone for users to understand the context (by reading what another user tried and failed to achieve) and to find possible solutions (avoiding the time sunk of dead-ends and maybe adapting an ugly hack into a cleaner solution, or even just using the ugly hack, instead of gving up on the use of Guix).

The low quality wiki could also motivate people to correct misconceptions and submit better approaches ("Someone is WRONG on the internet" https://xkcd.com/386/ ).

Re: Guix Documentation Meetup

[Ricardo Wurmus]

calcium <calcium@disroot.org> writes:

> I would like for Guix to host a community wiki (in addition to a more discoverable official documentation).

That’s the purpose of the Cookbook, which is open to all contributors.

-- 
Ricardo

Re: Guix Documentation Meetup

[calcium]

>> I would like for Guix to host a community wiki (in addition to a more discoverable official documentation).
> 
> That’s the purpose of the Cookbook, which is open to all contributors.
> 

It is not a wiki. You can't edit and review easly, but must instead send a contribution to someone (IRC or email) which is teadious and discourage small and quick contributions.

And my point was about allowing a low effort wiki that may contain wrong or incomplete content (but quick to contribute/use and where there is no expectation of high quality).

And this seems to go against the current spirit of hte Guix Cookbook (High quality/Without mistakes examples/content about howto do a specific task)

Re: Guix Documentation Meetup

[Matt]

 > > I would like for Guix to host a community wiki (in addition to a more discoverable official documentation).
 > 
 > That’s the purpose of the Cookbook, which is open to all contributors.

The cookbook is a great resource. I'd like to contribute to it.

Let me walk through what that looks like from my perspective.  I'm afraid, however, that it comes across as aggressive, ungrateful, or demanding.  None of those are my intent! I genuinely want to help but struggle to understand the process.  My goal is to outline a "user story".

From my perspective, contributing to the cookbook looks as follows.  I've tried to be factual and ask rhetorical questions. 

How do I contribute to the cookbook? I see no information in the cookbook about how to do that. I'm looking at https://guix.gnu.org/cookbook/en/guix-cookbook.html

The contribute page (https://guix.gnu.org/en/contribute/) links to this mailing list. I am willing and ready to contribute. Now what?

I see the manual has a section on contributing: https://guix.gnu.org/manual/en/html_node/Contributing.html#Contributing

I see nothing about how to contribute to documentation. 

Do I need to submit a patch? 
How do I submit a patch? 
Do I have to write in TexInfo?
What is the roadmap from me spending hours authoring something to it being available for review from experts or to being useful to others?

I see https://guix.gnu.org/manual/en/html_node/Commit-Access.html says I would need three people to vouche for me, have to apply for maintainership, and some other stuff I didn't read. 
Would anyone actually vouche for me at this point?

I have two documents written in Org:
1. http://excalamus.com/test-guix-case-study-plover-python-dictionary.html
2. http://excalamus.com/2021-10-06-guix-debug.html

Do I have to convert them to TexInfo?
Who will review them?
Is the layout and style appropriate for info distribution?
Are there any licensing concerns to be aware of?

To close, I apologise for how aggressive all the questions can feel. Reading over it is overwhelming, even for me.  I'm afraid it may come across as simply yelling "Why? Why? Why?"  I would like to help provide answers. However, it feels like myself and others are practically begging for direction on how to do that. Someone has the authority and means to address these issues. Who is that person and what is their gameplan for addressing the issues raised in this thread? How do I (and others) figure into that plan? How I and others fit into this community?

Thank you for your time and patience! (And for everyone, including you, Ricardo, who have contributed to making Guix something myself and others want to use and extend). 

Re: Guix Documentation Meetup

[Ricardo Wurmus]

Matt <matt@excalamus.com> writes:

>  > > I would like for Guix to host a community wiki (in addition to a more discoverable official documentation).
>  > 
>  > That’s the purpose of the Cookbook, which is open to all contributors.
>
> The cookbook is a great resource. I'd like to contribute to it.

Cool, we’re accepting contributions in whatever form you are comfortable
with.  Of course, patches are the easiest for us, but you can also just
write plain text and send it as an email to guix-patches@gnu.org or
guix-devel@gnu.org and ask for it to be added.

-- 
Ricardo

Re: Guix Documentation Meetup

[Leo Famulari]

On Sat, Jan 08, 2022 at 11:24:35AM -0500, Matt wrote:
> Let me walk through what that looks like from my perspective.  I'm afraid, however, that it comes across as aggressive, ungrateful, or demanding.  None of those are my intent! I genuinely want to help but struggle to understand the process.  My goal is to outline a "user story".
> 
> From my perspective, contributing to the cookbook looks as follows.  I've tried to be factual and ask rhetorical questions. 
> 
> How do I contribute to the cookbook? I see no information in the cookbook about how to do that. I'm looking at https://guix.gnu.org/cookbook/en/guix-cookbook.html
> 
> The contribute page (https://guix.gnu.org/en/contribute/) links to this mailing list. I am willing and ready to contribute. Now what?
> 
> I see the manual has a section on contributing: https://guix.gnu.org/manual/en/html_node/Contributing.html#Contributing
> 
> I see nothing about how to contribute to documentation. 
> 
> Do I need to submit a patch? 
> How do I submit a patch? 
> Do I have to write in TexInfo?
> What is the roadmap from me spending hours authoring something to it being available for review from experts or to being useful to others?

I see that this all seems confusing. If you have something to
contribute, you should just mail it to this list or guix-patches.
Definitely, we prefer you send patches, but if that is too hard, you can
send your contribution in *any* form.

Re: Guix Documentation Meetup

[Matt]

 > I see that this all seems confusing. 

Thank you for your response and for acknowledging my perspective.  Yes, I find many things about the documentation process confusing. I can't speak for others, but I get the strong sense that I'm not alone in that feeling.  

> If you have something to
> contribute, you should just mail it to this list or guix-patches.
> Definitely, we prefer you send patches, but if that is too hard, you can
> send your contribution in *any* form.

I did.  Maybe you missed the two blog posts I linked in the previous email?    

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

The first is a tutorial of creating a non-trivial Guix package.  The second analyzes the process of troubleshooting an issue.

I share them here for two reasons. 

First, the packaging tutorial is, I believe, a reasonable candidate for the cookbook.  It's ready for feedback toward inclusion, not direct inclusion.  The software being packaged isn't ideal as it involves concepts which may detract from the main subject of packaging, like stenography. It's also for a plugin and not standalone software.  Demonstrating the final package requires demonstrating the parent application which again detracts from the main subject of packaging.  Finally, it's written using active voice which conveys authority on the topic, authority I don't actually have. This was my first attempt at packaging.

Second, the troubleshooting post is not, in my option, suited for the cookbook. It is, however, a good candidate for a wiki page (similar to Arch wiki sections on troubleshooting).  The last time a wiki was talked about, it seems, was in 2015. I'll start a thread for that.

Re: Guix Documentation Meetup

[André A. Gomes]

Matt <matt@excalamus.com> writes:

>  > I see that this all seems confusing.
>
> Thank you for your response and for acknowledging my perspective.
> Yes, I find many things about the documentation process confusing. I
> can't speak for others, but I get the strong sense that I'm not alone
> in that feeling.

You're not alone, but honestly I think Guix's efforts are heroic to say
the least.  How many software has no documentation at all?  I always
gaze at the quality of Guix's manual.

> First, the packaging tutorial is, I believe, a reasonable candidate
> for the cookbook.  It's ready for feedback toward inclusion, not
> direct inclusion.  The software being packaged isn't ideal as it
> involves concepts which may detract from the main subject of
> packaging, like stenography. It's also for a plugin and not standalone
> software.  Demonstrating the final package requires demonstrating the
> parent application which again detracts from the main subject of
> packaging.  Finally, it's written using active voice which conveys
> authority on the topic, authority I don't actually have. This was my
> first attempt at packaging.
>
> Second, the troubleshooting post is not, in my option, suited for the
> cookbook. It is, however, a good candidate for a wiki page (similar to
> Arch wiki sections on troubleshooting).  The last time a wiki was
> talked about, it seems, was in 2015. I'll start a thread for that.

Please don't misinterpret the following comments.  You're doing
something valuable for the community by the mere fact of talking about
Guix - your writings are valuable!  But I don't see how the 1st one
could land in a cookbook.  Regarding the 2nd and the wiki, as someone
(perhaps you) already noted, wikis generally host low quality content.
Guix's documentation has a ton of examples, perhaps even too many for an
expository kind of text.  Yes, I'm not a fan of wiki.  Regardless, the
efforts of such a wiki should perhaps land outside the scope of Guix
(i.e. it should be non-"official").

I'm not connected with Guix with any way - a mere enthusiast and
observer.

I hope you continue to write great articles like these!


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

Re: Guix Documentation Meetup

[Matt]

 > Please don't misinterpret the following comments.  But I don't see how the 1st one
 > could land in a cookbook.  

You're fine, I more or less agree with you. I think something like it with a different package would be helpful.  What I wrote probably isn't it.

 > Yes, I'm not a fan of wiki.  Regardless, the
 > efforts of such a wiki should perhaps land outside the scope of Guix
 > (i.e. it should be non-"official").

I started a thread to talk about a Guix wiki. I'd like to hear  more of your thoughts about it.

 > I'm not connected with Guix with any way - a mere enthusiast and
 > observer.

I'm not sure what you mean.  Being excited about something and taking the time to observe it, like listening to music, is a connection, right?  

This conversation is a great example of how documentation affects community and engagement.  Your perspective is valuable!  

I'm curious, what makes you feel not connected with Guix?

 > I hope you continue to write great articles like these!

I appreciate the encouragement.  Thank you.

Re: Guix Documentation Meetup

[André A. Gomes]

Matt <matt@excalamus.com> writes:

>  > I'm not connected with Guix with any way - a mere enthusiast and
>  > observer.
>
> I'm not sure what you mean.  Being excited about something and taking
> the time to observe it, like listening to music, is a connection,
> right?

I mentioned because ultimately the final word isn't mine :)

> I'm curious, what makes you feel not connected with Guix?

I feel connected "philosophically" as a (basic) user, but not as a
contributor.  Guix, by itself, is a complex system.  Honestly, I suck at
using Guile in a project of this scale (no, I don't think the
documentation is poor).  I have some understanding in Emacs and
slime/common lisp systems, but I still need to dive into geiser.  There
are difficulties of other sorts as well.  This is a Unix system and that
fact alone requires knowledge and experience.  I assume that most core
contributors are/were involved in other efforts such as Debian, Arch,
Gentoo, etc.  Besides experience in "system administration" and HPC.

I don't know how many people in the community have
non-CS/Unix/programming backgrounds so I share some personal thoughts
below.  It's not that I want to share my life, but it might resonate
with the experiences of others.

My background is in theoretical physics and pure maths.  I never cared
about computers or computation, until I had to find a job circa 2018.  I
landed on a wind energy company which owns a supercomputer (running
GNU/Linux of course), and without me realising, I was being "forced" to
be a software developer.  I had to learn a lot and fast.  Soon, I
understood that the bottleneck on the success of a given project isn't
in the lack of domain-specific/scientific knowledge, but in the lack of
robust (software) tools and "software knowledge" in general.  Most
"scientists" think: "these IT/programmers can't do their work properly".
This division ("scientists" and "programmers") is toxic.  Yes, it's VERY
hard to find people who do both well.  Guix a step towards tearing this
wall apart for good.  It's not by chance that Guix has a strong presence
on HPC.  (Yes, it's hell to depend on an admin to install stuff).  It's
interesting to note that the effort comes from the "programmers" side.
I think the bottleneck on Guix's world domination is precisely because
"scientists" generally make little effort in that regard.  It's hard to
make "non-sexy" things look sexy.  Go and tell a "data-scientist" about
reproducible builds.  Good luck.

It's ok if things are overwhelming and hard.  Things eventually click
and start to make sense.  


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

Re: Guix Documentation Meetup

[Matt]

 > I don't know how many people in the community have
 > non-CS/Unix/programming backgrounds so I share some personal thoughts
 > below.  It's not that I want to share my life, but it might resonate
 > with the experiences of others.

Thank you for sharing your story. It resonates with me as mine is similar.  I have degrees in math and statistics,  and am a self-taught programmer. I've worked a lot with scientists and engineers and have experienced the divide you describe. It can be a hard gap to bridge.

It a sounds like one of the things that makes you feel disconnected from Guix is your current skill level with Guile, Geiser, and general Unix knowledge. I can sympathize.  I've had the same kinds of challenges as were described by people earlier in the thread.

Re: Guix Documentation Meetup

[Leo Famulari]

On Sun, Jan 09, 2022 at 04:12:57PM -0500, Matt wrote:
> I did.  Maybe you missed the two blog posts I linked in the previous email?    

Yeah, I did miss that you intended to contribute them.

There is another side of my advice about submitting your contributions
however you can: It's still important to try to communicate clearly.
Your message includes several paragraphs of meta-discussion before
mentioning that you have some things to contribute, rather than just a
desire to contribute in general. Based on that, both me and Ricardo did
not understand that your blog posts were potential contributions.

Sorry if that comes across as harsh, but it's always true that
successful collaboration is helped by clear and concise communication.

Maybe that's a good thing, maybe it's a bad thing. It's the reality in
any collaborative environment where people are busy.

So, if you have a goal, my advice is to state it clearly and concisely.

If you have both long-term goals (make it easier to contribute
documentation) and short-term goals (add some Cookbook recipes or wiki
pages), then you should present them separately, or else people will
only focus on one of them.

Re: Guix Documentation Meetup

[Matt]

 ---- On Wed, 12 Jan 2022 13:41:10 -0500 Leo Famulari <leo@famulari.name> wrote ----
 > On Sun, Jan 09, 2022 at 04:12:57PM -0500, Matt wrote:
 > > I did.  Maybe you missed the two blog posts I linked in the previous email?    
 > 
 > Yeah, I did miss that you intended to contribute them.
 > 
 > There is another side of my advice about submitting your contributions
 > however you can: It's still important to try to communicate clearly.
 > Your message includes several paragraphs of meta-discussion before
 > mentioning that you have some things to contribute, rather than just a
 > desire to contribute in general. Based on that, both me and Ricardo did
 > not understand that your blog posts were potential contributions.
 > 
 > Sorry if that comes across as harsh, but it's always true that
 > successful collaboration is helped by clear and concise communication.
 > 
 > Maybe that's a good thing, maybe it's a bad thing. It's the reality in
 > any collaborative environment where people are busy.
 > 
 > So, if you have a goal, my advice is to state it clearly and concisely.
 > 
 > If you have both long-term goals (make it easier to contribute
 > documentation) and short-term goals (add some Cookbook recipes or wiki
 > pages), then you should present them separately, or else people will
 > only focus on one of them.
 > 

This is good advice. I will take it to heart. I see how the ways I approached things didn't set things up for success. Thank you.

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


Cheers,
simon

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

Re: Planet of Guix-related posts?

[Matt]

 ---- On Mon, 10 Jan 2022 10:21:51 -0500 zimoun <zimon.toutoune@gmail.com> 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?

[André A. Gomes]

Matt <matt@excalamus.com> writes:

>  ---- On Mon, 10 Jan 2022 10:21:51 -0500 zimoun <zimon.toutoune@gmail.com> 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?

[Ricardo Wurmus]

Matt <matt@excalamus.com> 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?

[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 <matt@excalamus.com> writes:

>  ---- On Mon, 10 Jan 2022 10:21:51 -0500 zimoun <zimon.toutoune@gmail.com> 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: Guix Documentation Meetup

[Leo Famulari]

On Sat, Jan 08, 2022 at 11:24:35AM -0500, Matt wrote:
> 2. http://excalamus.com/2021-10-06-guix-debug.html

The error about "profile contains conflicting entries" is something we
should improve the documentation about, for sure.

I opened a tracking bug about it: 

https://issues.guix.gnu.org/53224

I think we can adapt some older presentations (video-recorded) about
Guix, because they helped me understand the subject quite clearly when I
watched them when I first learned about Guix.

The manual's treatment of profiles and propagation is authoritative and
correct, but it does not quite communicate the subject in a way that
combines to make these error messages understandable.

Re: Guix Documentation Meetup

[ilmu]

[-- Attachment #1: Type: text/plain, Size: 477 bytes --]

Funny how many maths people immediately jump on the reproducible builds idea when "self-educating" themselves about computers.

I have a slightly different take on the documentation situation but I'm a bit of a crackpot so don't mind me... We need a multi-purpose menu program (fzf is a proof of concept but not good enough to be the "start menu" of linux). The pdf I attached is my wip draft to give a talk at ELS2022, maybe it makes sense to you.

Kind regards,
- Ilmu

[-- Attachment #2: Datalisp Technical Report - final draftfix.pdf --]
[-- Type: application/pdf, Size: 876938 bytes --]

Re: Guix Documentation Meetup

[Matt]

 > I would like for Guix to host a community wiki

Agreed. 

Ironically, Guix already has two of them.

1. goto gnu.guix.org
2. Select wiki from the help menu
3. Discover that linked wiki is not a community wiki
4. Click the (supposed) community wiki: https://guix.miraheze.org/wiki/Main_Page

Is this the "official" Guix wiki? 
If so, why is it not a direct link from the home page.
Who hosts it? If I spend hours writing something, is it just going to disappear some day?

Re: Guix Documentation Meetup

[Julien Lepiller]

Le 8 janvier 2022 14:41:53 GMT+01:00, Matt <matt@excalamus.com> a écrit :
>
> > I would like for Guix to host a community wiki
>
>Agreed. 
>
>Ironically, Guix already has two of them.
>
>1. goto gnu.guix.org
>2. Select wiki from the help menu
>3. Discover that linked wiki is not a community wiki
>4. Click the (supposed) community wiki: https://guix.miraheze.org/wiki/Main_Page
>
>Is this the "official" Guix wiki? 
>If so, why is it not a direct link from the home page.
>Who hosts it? If I spend hours writing something, is it just going to disappear some day?
>

Someone was frustrated there was no wiki, so they started that, but it's not official at all. Miraheze hosts other wikis, like the bootstrappable wiki, I think it's ok, but if we had a wiki, it should rather be hosted on gnu or guix infrastructure.

Re: Guix Documentation Meetup

[Matt]

 > Someone was frustrated there was no wiki, so they started that, but it's not official at all. Miraheze hosts other wikis, like the bootstrappable wiki, I think it's ok, but if we had a wiki, it should rather be hosted on gnu or guix infrastructure.
 
Thank you for clarifying. I now see the footer says "unofficial". 

Re: Guix Documentation Meetup

[Josselin Poiret]

Hello everyone,
Matt <matt@excalamus.com> writes:

>  > I would like for Guix to host a community wiki
>
> Agreed. 
>
> Ironically, Guix already has two of them.
>
> 1. goto gnu.guix.org
> 2. Select wiki from the help menu
> 3. Discover that linked wiki is not a community wiki
> 4. Click the (supposed) community wiki: https://guix.miraheze.org/wiki/Main_Page
>
> Is this the "official" Guix wiki? 
> If so, why is it not a direct link from the home page.
> Who hosts it? If I spend hours writing something, is it just going to disappear some day?

If I remember correctly, this wiki was created by Jacob "Kreyren" Hrbek
<kreyren@rixotstudio.cz> [1, 2], however they seem to have been banned from
IRC some time ago [3].  miraheze.org itself seems to be a wiki farm, but
I don't know if there are any advantages over LibrePlanet.  I think it
would be very possible to turn the current Group:Guix wiki into a proper
Community wiki, just that it's not used in that way currently.

[1] https://logs.guix.gnu.org/guix/2021-11-03.log#215121
[2] https://libreplanet.org/wiki/Special:Contributions/Kreyren
[3] https://logs.guix.gnu.org/guix/2021-11-28.log#015743

-- 
Josselin Poiret