Re: Guix Documentation Meetup

[Raghav Gururajan]

Hello Guix!


DATE: Saturday, March 19, 2022.
TIME: 15:00 UTC
Duration: ~1.5hrs


Oops! Forgot to add the meeting link.

LINK: https://meet.nixnet.services/b/rag-8bi-sdx-kdf

P.S.
Thanks to NixNet for providing BBB service.

Regards,
Raghav "RG" Gururajan.


OpenPGP_signature
Description: OpenPGP digital signature

Re: Guix Documentation Meetup This Saturday (January 15)

[jgart]

On Tue, 11 Jan 2022 11:29:44 -0500 jgart  wrote:
> On Tue, 11 Jan 2022 17:23:38 +0100 Oliver Propst  
> wrote:
> > On 2022-01-11 17:01, jgart wrote:
> > > Hi Guixers,
> > 
> > Hi Jgart thanks for the *note.
> > 
> > *will try to attend the meeting.
> 
> Hi Oliver,
> 
> Cool, hope to see you there!
> 
> all best,
> 
> jgart
> 

Hi Guixers,

We had a great turn out and insightful discussions about contibuting to and
documenting Guix.

Here are the notes and chat log the people added to BBB from today's
Guix Documentation Meetup:

https://paste.sr.ht/~whereiseveryone/69bad7722fad84edb1d6bed1f2c95b6e138f8154

https://paste.sr.ht/~whereiseveryone/11142d27dbe26732a8f5745e918ead9014b848f6

Our patch to upstream:

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

Hope to catch you on the next one!

all best,

jgart

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

[Matt]

  On Wed, 12 Jan 2022 13:41:10 -0500 Leo Famulari  
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.

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 Tue, 11 Jan 2022 21:57:03 -0500 Matt  wrote 
 > 
 >   On Tue, 11 Jan 2022 20:20:30 -0500 jgart  wrote 
 > 
 >  > Have you read ambrevar's post called 'Guix Profiles in Practice'?
 > > 
 >  > Unfortunately ambrevar's blog seems to be down at the moment:
 >  > 
 >  > https://ambrevar.xyz/guix-profiles/index.html
 >  > 
 > 
 > No, I haven't. Thanks!
 > 
 > It's archived: 
 > https://web.archive.org/web/20210415041114/https://ambrevar.xyz/guix-profiles/index.html
 
Actually, I have.  It's in the cookbook, (guix-cookbook) Guix Profiles in 
Practice.  

Re: Guix Documentation Meetup

[Matt]

  On Tue, 11 Jan 2022 20:20:30 -0500 jgart  wrote 

 > Have you read ambrevar's post called 'Guix Profiles in Practice'?
> 
 > Unfortunately ambrevar's blog seems to be down at the moment:
 > 
 > https://ambrevar.xyz/guix-profiles/index.html
 > 

No, I haven't. Thanks!

It's archived: 
https://web.archive.org/web/20210415041114/https://ambrevar.xyz/guix-profiles/index.html

 > > Cohesion is a big point in my outline. Maybe I could check for that as
 > > regards profiles?  
 > 
 > > Otherwise, maybe look over the contribute section. It
 > > seems like I could use a rereading of it. If there's anything that's
 > > unclear, the meeting might be a good space to address it.
 > 
 > roptat made a nice guide for learning texinfo:
 > 
 > https://learnxinyminutes.com/docs/texinfo/
 
Cool, it's been a bit since I used texinfo

Re: Guix Documentation Meetup

[jgart]

On Tue, 11 Jan 2022 19:59:37 -0500 Matt  wrote:
>   On Tue, 11 Jan 2022 11:24:20 -0500 jgart  wrote 
> 
>  > I'm looking forward to having you at the next docs meetup:
>  > 
>  > https://lists.gnu.org/archive/html/guix-devel/2022-01/msg00189.html
>  > 
>  > Are there any particular sections in the guix manual that you would like
>  > to work on in the meetup?
> 
> I outlined some interests here:  
> https://lists.gnu.org/archive/html/guix-devel/2022-01/msg00105.html

Hi Matt,

I skimmed that thread. Let me reread and I'll keep it in mind for this
Saturday's meetup. Thank you for taking the time to share your thoughts
and user experiences with guix.

> I was just learning about profiles and how to use them to install
> multiple versions of a software. So, my head is there at the moment.

Have you read ambrevar's post called 'Guix Profiles in Practice'?

Unfortunately ambrevar's blog seems to be down at the moment:

https://ambrevar.xyz/guix-profiles/index.html

> Cohesion is a big point in my outline. Maybe I could check for that as
> regards profiles?  

> Otherwise, maybe look over the contribute section. It
> seems like I could use a rereading of it. If there's anything that's
> unclear, the meeting might be a good space to address it.

roptat made a nice guide for learning texinfo:

https://learnxinyminutes.com/docs/texinfo/

I'm also accepting patches for the guixrus wiki on sourcehut:

https://man.sr.ht/~whereiseveryone/guixrus/

Patches can be sent to ~whereiseveryone/guix...@lists.sr.ht

The guixrus wiki is being used by the whereiseveryone community as a
staging area for discussing proposals to upstream docs and for any guix
docs that are not ready for whatever reason. I can usually review and
merge any docs for the guixrus wiki within a day or two of submitting
it. If not, ping me on irc.

We accept guixrus wiki docs in markdown. When sending anything in the
guixrus wiki make sure to translate it to texinfo. You can use pandoc
to assist with that. I'll add an entry to the wiki soon for instructions
on how to do that:

```
guix shell pandoc -- pandoc index.md -o index.texi
```

If you'd like to discuss more about the guixrus wiki come chat with us
at #whereiseveryone on the irc.libera.chat network.

> Mainly, I'm interested in getting to meet you and others from the
> community and hear what they value.

Likewise! I'm looking forward to meeting you also and everyone that
might show up.

all best,

jgart

gemini://whereiseveryone.srht.site/
https://whereiseveryone.srht.site/

Re: Guix Documentation Meetup

[Matt]

  On Tue, 11 Jan 2022 11:24:20 -0500 jgart  wrote 

 > I'm looking forward to having you at the next docs meetup:
 > 
 > https://lists.gnu.org/archive/html/guix-devel/2022-01/msg00189.html
 > 
 > Are there any particular sections in the guix manual that you would like
 > to work on in the meetup?

I outlined some interests here:  
https://lists.gnu.org/archive/html/guix-devel/2022-01/msg00105.html

I was just learning about profiles and how to use them to install multiple 
versions of a software. So, my head is there at the moment.  Cohesion is a big 
point in my outline. Maybe I could check for that as regards profiles?  
Otherwise, maybe look over the contribute section. It seems like I could use a 
rereading of it. If there's anything that's unclear, the meeting might be a 
good space to address it.

Mainly, I'm interested in getting to meet you and others from the community and 
hear what they value.

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 This Saturday (January 15)

[jgart]

On Tue, 11 Jan 2022 17:23:38 +0100 Oliver Propst  
wrote:
> On 2022-01-11 17:01, jgart wrote:
> > Hi Guixers,
> 
> Hi Jgart thanks for the *note.
> 
> *will try to attend the meeting.

Hi Oliver,

Cool, hope to see you there!

all best,

jgart

Re: Guix Documentation Meetup

[jgart]

On Mon, 10 Jan 2022 08:15:34 -0500 Matt  wrote:
> > Also if I understand things correctly there are 
>  > actually plans to host a documentation meetup this Saturday (maybe at 
>  > around 10:30 AM ET as the last ones).
>  
> Thank you!  I should be able to attend.
> 
> Is that January 15, at 10:30 am EST using 
> https://meet.nixnet.services/b/jga-rtw-ahw-yky?
> 
> Was that announced anywhere?

Hi Matt,

I'm looking forward to having you at the next docs meetup:

https://lists.gnu.org/archive/html/guix-devel/2022-01/msg00189.html

Are there any particular sections in the guix manual that you would like
to work on in the meetup?

all best,

jgart

Re: Guix Documentation Meetup This Saturday (January 15)

[Oliver Propst]

On 2022-01-11 17:01, jgart wrote:

Hi Guixers,


Hi Jgart thanks for the *note.

*will try to attend the meeting.
--
Kinds regards Oliver Propst
https://twitter.com/Opropst

Re: Guix Documentation Meetup

[André A . Gomes]

Matt  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]

 > 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

[Matt]

> Also if I understand things correctly there are 
 > actually plans to host a documentation meetup this Saturday (maybe at 
 > around 10:30 AM ET as the last ones).
 
Thank you!  I should be able to attend.

Is that January 15, at 10:30 am EST using 
https://meet.nixnet.services/b/jga-rtw-ahw-yky?

Was that announced anywhere?

> I'm sure your participation and potential contributions to the 
> documentation meetup would be very welcome at this point in time :)

I hope so. I look forward to meeting everyone and hearing their thoughts.

Re: Guix Documentation Meetup

[Oliver Propst]

Hi Matt I thanks for your very elaborate and insightful mail. As a Guix 
user and enthusiast I definitely agree that documentation is important 
for the project. Also if I understand things correctly there are 
actually plans to host a documentation meetup this Saturday (maybe at 
around 10:30 AM ET as the last ones).


On 2022-01-08 05:52, Matt wrote:

I want to be a part of this.  I feel like I've been rubbing two sticks
together while it seems some people out there have Zippo lighters

Cool.


One final question:

  How might announcements of the "Guix Documentation Meetup" (and
"Guix Packaging Meetup)" be made more prominent?

I check the mailing list from time to time, but missed the
announcements because they were buried.  Maybe meetings could be
announced on info-guix?


Sounds as good ideas to me and something that I think the project should 
consider.



If they become regular, maybe put them on
https://guix.gnu.org/en/contribute/?  FWIW, I'm willing to be present
so that a documentation meetup could run monthly. I'm an FSF member
and could use the FSF Jitsi service if I needed to host it.  I've not
used Big Blue Button before.


I'm sure your participation and potential contributions to the 
documentation meetup would be very welcome at this point in time :)

Re: Guix Documentation Meetup

[André A . Gomes]

Matt  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]

 > 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

[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

[Ricardo Wurmus]

Matt  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-patc...@gnu.org or
guix-devel@gnu.org and ask for it to be added.

-- 
Ricardo

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

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

Re: Guix Documentation Meetup

[Julien Lepiller]

Le 8 janvier 2022 14:41:53 GMT+01:00, Matt  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]

 > 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

[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

[Ricardo Wurmus]

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

[Matt]

I want to be a part of this.  I feel like I've been rubbing two sticks together 
while it seems some people out there have Zippo lighters. A real-time 
conversation, some paired programming, or simply looking over the shoulder of 
someone who knows what they're doing would go a long way.  I have been trying 
to learn and share by way of case studies: www.excalamus.com.  My hope is that 
these could one day be adapted for the manual, or at least prep me for making 
meaningful contributions to the official documentation.  I have several more 
studies that are unpublished.

I share many of the same challenges others have experienced, certainly with 
Guile.

These are things I'm interested in helping with:

* defining terms

  A glossary, improved indexing (which is there), and more references (also 
present), are things I want to help with.

  For example, I've spent the past few days' free time trying to understand how 
to install an old version of ungoogled-chromium, required for Jitsi. To do this 
required 1) knowing what a profile is and 2) knowing the syntax of "sourcing".  
First, a profile is mentioned in passing several times in the manual as a 
directory. Yet, the guix package --profile option requires a *file* be 
specified.  (yes, a directory is a file, but guix complains if you pass a 
directory). So, is a profile a file or a directory? After much poking around, I 
found that the file specified by the --profile option is a symlink. This 
symlink points to another symlink (specifying the generation?), which in turn 
appears to point to the directory of packages . So, a profile *is* a directory, 
but, depending on how you look at it, it may be a file. Second, to activate the 
profile requires "sourcing" $GUIX_PROFILE/etc/profile (again, is a profile a 
file or a directory?). Some parts of the documentation give this as:

GUIX_PROFILE="$HOME/.guix-profile" . "$GUIX_PROFILE/etc/profile"

  Nevermind having to look up what was meant by "sourcing", I did that. But it 
turns out that there are two syntaxes for it: the one above and the more clear 
`source "$GUIX_PROFILE/etc/profile"`. Of course, with my luck, that wasn't made 
clear with the resources I found. It took me far too long to see how what I 
found on the open web corresponded to the manual.

* meaning/consequences/significance

  Knowing words without understanding the consequences of their meaning is just 
memorizing jargon. A profile is a directory? So what? Is that significant or 
just trivia? I still don't know.  Sometimes I think I'm reading about the Turbo 
Encabulator (https://www.youtube.com/watch?v=Ac7G7xOG2Ag)

* context/workflows

  I want to help show what it means for Guix to be imperative and declarative.  
Each has a different workflow, it seems, and the manual mixes those together. 
The context isn't always clear.

  Guix is flexible.  It can be complicated, but isn't by necessity.  I've been 
able to get by for nearly a year doing, more or less, guix pull, guix package 
-u, and occasionally guix system reconfigure (with a few guix installs thrown 
in :) Almost all the complex stuff has been from my choice to learn and do more.

  The simple daily workflows aren't apparent to me from the documentation. I 
don't need to code a config or define packages or set up channels or profiles 
or do any of that unless I want to? It took a bit of reading for me to realize, 
that's it?  I think there's a big focus on what can be done with Guix and not 
much said about the boring routine stuff. As a new user (even as a somewhat 
less new user), that's what I need first: I need security that my system will 
work, not crash or destroy my data and not consume my life *unless I choose for 
it to*. Isn't that really what Guix has to offer? Show me.

* navigation/discoverablity

  Guix is described as "the Emacs of distros".  To me Emacs, besides embodying 
freedom, means self-documenting. I wouldn't be a professional programmer 
without Emacs. It nurtures me by answering questions, giving examples, and 
scaffolding learning.  Emacs expands the zone of proximal development 
(https://en.wikipedia.org/wiki/Zone_of_proximal_development) and ensures I can 
achieve what I couldn't before.

  Guix is poised to do the same. However, the documentation and my difficulty 
navigating it is a huge problem for me.

  Others have touched on it when talking about Guile.

  - Is this symbol from Guile or Guix?
  - What does it do?
  - How is it used?
  - How many steps are required for someone to answer these questions?
(answer: not one like, C-h f. Instead, it might be days searching the 
mailing list, getting familiar with IRC, and being lucky with timing and and 
experimenting)
  - Geiser seems great. How the f*** does it help me answer these
questions? Wait, what problem am I trying to solve again?

  I love the info system.  Google has nothing on the info reader.  Yet even the 
info system's ability to overcome the documentation trilemma 

Re: Guix Documentation Meetup

[Katherine Cox-Buday]

adriano  writes:

> Il giorno dom, 12/12/2021 alle 21.50 -0600, Katherine Cox-Buday ha scritto:

>> - In geiser, run =,a thing-i-want-to-look-for= (this is supposedly an
>> apropos command that is supposed to search symbols for you). The command
>> returns nothing.

> about this, I want to report an example
>
> scheme@(guile-user)> (help tail)
> Did not find any object named `tail'
> scheme@(guile-user)> 
>
> BUT
>
> scheme@(guile-user)> (help "tail") <-- notice the quotation marks !
> Documentation found for:

> That is, help with the quotation marks reports about things even if
> they're in namespaces you haven't imported yet !

Thank you very much for the tip! I will definitely be trying this next time I'm 
hacking on Guile!

-- 
Katherine

Re: Guix Documentation Meetup

[adriano]

Il giorno dom, 12/12/2021 alle 21.50 -0600, Katherine Cox-Buday ha
scritto:



> - In geiser, run =,a thing-i-want-to-look-for= (this is supposedly an
> apropos
>   command that is supposed to search symbols for you). The command
> returns
>   nothing. I realize I have to import the module implementing the
> thing I'm
>   looking for first, thus defeating the purpose.

about this, I want to report an example

scheme@(guile-user)> (help tail)
Did not find any object named `tail'
scheme@(guile-user)> 


BUT


scheme@(guile-user)> (help "tail") <-- notice the quotation marks !
Documentation found for:
(language cps): $ktail
(language tree-il): seq-tail
(language tree-il): abort-tail
(guile): list-tail
(guile): make-struct/no-tail
(srfi srfi-1): find-tail
(system vm assembler): emit-tail-call-label
(system vm assembler): emit-tail-call
(system vm assembler): emit-tail-pointer-ref/immediate
(ice-9 vlist): vlist-tail

`$ktail' is an object in the (language cps) module.

- Variable: $ktail


`seq-tail' is a procedure in the (language tree-il) module.

- Variable: seq-tail


`abort-tail' is a procedure in the (language tree-il) module.

- Variable: abort-tail


`list-tail' is a procedure in the (guile) module.

- Function: list-tail _ _
 - Scheme Procedure: list-tail lst k
 
 
  Return the "tail" of LST beginning with its Kth element.  The
first
  element of the list is considered to be element 0.
 
  `list-tail' and `list-cdr-ref' are identical.  It may help to
think
  of `list-cdr-ref' as accessing the Kth cdr of the list, or
  returning the results of cdring K times down LST.



`make-struct/no-tail' is a procedure in the (guile) module.

- Function: make-struct/no-tail _ .  _
 - Scheme Procedure: make-struct/no-tail vtable .  init
  Create a new structure.
 
  VTABLE must be a vtable structure (see Vtables).
 
  The INIT1, ... are optional arguments describing how
successive
  fields of the structure should be initialized.  Note that
hidden
  fields (those with protection 'h') have to be manually set.
 
  If fewer optional arguments than initializable fields are
supplied,
  fields of type 'p' get default value #f while fields of type
'u'
  are initialized to 0.



`find-tail' is a procedure in the (srfi srfi-1) module.

- Function: find-tail pred lst
 Return the first pair of LST whose CAR satisfies the predicate
 PRED, or return `#f' if no such element is found.



`emit-tail-call-label' is a procedure in the (system vm assembler)
module.

- Function: emit-tail-call-label asm t-ff72ee5a3696d21-378b


`emit-tail-call' is a procedure in the (system vm assembler) module.

- Function: emit-tail-call asm


`emit-tail-pointer-ref/immediate' is a procedure in the (system vm
assembler) module.

- Function: emit-tail-pointer-ref/immediate asm t-ff72ee5a3696d21-3ac6
t-ff72ee5a3696d21-3ac7 t-ff72ee5a3696d21-3ac8


`vlist-tail' is a procedure in the (ice-9 vlist) module.

- Function: vlist-tail vlist
 Return the tail of VLIST.


That is, help with the quotation marks reports about things even if
they're in namespaces you haven't imported yet !


I'm confused about the difference between help withouth and with the
quotation marks

In fact

scheme@(guile-user)> ,a tail
(guile): list-tail  #
(guile): make-struct/no-tail#


apropos does find at least something, but

scheme@(guile-user)> (help tail)
Did not find any object named `tail'


help with no quotation marks finds nothing !

Why is this so ?

I can't fathom that ¯\_(ツ)_/¯

And I can't even remember how I discovered this behaviour

I remember I was quite puzzled when I did

This is hidden and arbitrary

But it IS like that !

So maybe this little trick can make your sessions a bit less
frustrating !

"tail" was just a silly example I was able to come up with

I'd be curious to try with some of your things :-)

Bye
Adriano

Re: Guix Documentation Meetup

[adriano]

Il giorno sab, 11/12/2021 alle 05.40 +0700, Blake Shaw ha scritto:
> 
> hiya guix,
> 
> @cybersyn from IRC here, I recently contributed my first package,
> [notcurses]
> 
> --
> tldr: is there also room to discuss contributing -- and possibly
> doing a
> sizeable makeover to -- the *Guile* documentation? If so, I could
> give a
> short 5 - 10 minutes presentation of what I think should be done (and
> would volunteer to do).
> --

I'm reading this on december 21st

I suppose the documentation meetup happened already and I don't know if
you gave your illustration of your notes

I, for one, would LOVE to hear it

Yes the Guile experience is abysmal, awful, actively rejecting
beginners/newcomers

I've been wandering in the Guile manual, on and off, for years now and
I still can't make any sense of it

If I have a curiosity I still can't find my way around to such thing in
the manual, most of my discoveries have been by pure chance

Often, I try to re-read the same thing a few months later and I can't
find it again

Everytime I attempted something in Guile I've been frustrated

I myself have done a so called vlog where I show how to read a file in
Guile

I also have a general view of packaging and distributing Guile packages
that I gained by some very hard work that lasted a couple of years but
I was discouraged in doing more videos

Not only previous knowledge of the GNU system is a not declared hard
requirement

Often, previous knowledge of other things is required too

For example the new exceptions system is obscure, you're required to
know the one from Common Lisp in order to undertsand the one in Guile

Or,as another example, I stumbled in an example made in python of a
hashmap (similar to the ones very common in Clojure) and I got that

Good luck with data structured in Scheme

Or, the machinery for manipulating xml (and json ?) trees is discussed
in academic (!!) papers that present the code in Haskell, so you need
to learn Haskell in order to read that

The curse of knowledge in the Guile world is tragic



> I think I can personally offer a lot in terms of contributing to
> documentation. While I don't serious experience w/technical writing,
> prior to the pandemic I was doing my PhD in philosophy of
> mathematics,
> so I come from a cross-disciplinary background that involves the
> often
> difficult area of communicating new, formal ideas to previously
> unexposed readers. I've also made a living as a new media artist
> since
> 2009, working mostly in C and C++ based frameworks, so I also have
> some
> knowledge of the difficulties "crafters" have when learning new
> development systems.

That's all good. I love that you noticed the problem and are offering a
fresh perspective 

> I don't know if this is the correct forum for it, but I personally
> think
> the biggest documentation obstacle in Guix at the moment isn't so
> much
> in Guix, but instead in Guile. 

Absolutely, yes

> I found Guix via SICP & Racket about a
> year ago, and I remained a happy Racket hacker until a couple months
> ago
> when I decided to devote my free time to learning Guile in hopes of
> graduating to a Guix sensei one day.

Not only a Guix sensei but maybe a Guile sensei

Why has Guile only Guix ?

Why couldn't we have more nice things made in Guile ?

> While I've come to love Guile, compared to my experience with Racket
> its
> been quite burdensome for me to get in the hang of, something I
> attribute
> primarily to the structure of the docs, and not due to it being in
> any
> way more difficult than Racket. While with Racket I was writing
> useful programs in the standard #lang within my first week, with
> Guile
> I often find that what should be almost trivial winds up with a lot
> of
> time lost just trying to navigate and understand the docs. When I do
> figure things out, it turns out to be no more difficult than the
> equivalent
> in Racket, but a lack of consistency in the path that leads there in
> the
> docs cause hangups, which has made trivial scripts that should take
> an hour
> become weekend projects.
> 
> I know this isn't the Guile list, but when I've written on this topic
> in
> the IRC I've had no response, which make me think docs could be a
> bit of a bikeshedding topic in the community. But as Guile is
> fundamental to Guix and theres a lot of crossover btwn the
> communities,
> it seems like this could be a good time to raise these suggestions.

Oh I love this !

> I've jotted down some notes on several concrete examples of where the
> docs
> diverge from stylistic consistency, as well as some light analysis as
> to
> why such seemingly small inconsistencies can lead to such hangups in
> the learning
> process. If folks would be interested in me presenting a short 5-
> 10min
> presentation of these notes, I'd be happy to share.

yes plase !!!


> Sorry for such a long-winded message! Personally, good documentation
> is
> absolutely essential, and I feel like I could give Guile's docs a
> 

Re: Guix Documentation Meetup

[jgart]

On Wed, 15 Dec 2021 20:12:48 +0100 zimoun  wrote:

Hi all,

Just wanted to share the patches here from the meetup:

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

all best,

jgart

Re: Guix Documentation Meetup

[zimoun]

Hi,

On Wed, 15 Dec 2021 at 18:37, Blake Shaw  wrote:
>
> Blake Shaw  writes:
>
> Simon, just peeped your monad tutorial, and gotta say its one of the
> clearest presentations of the subject I've seen. Great work!

Thanks.  If it helps, I can share the Org source file.


Cheers,
simon

Re: Guix Documentation Meetup

[Blake Shaw]

Blake Shaw  writes:

Simon, just peeped your monad tutorial, and gotta say its one of the
clearest presentations of the subject I've seen. Great work!

>> I agree.  For what it is worth, I tried once to quickly explain monad,
>> with the aim of “Store Monad“ in mind,
>>
>> https://guix.gnu.org/manual/devel/en/guix.html#The-Store-Monad
>>
>> After several discussions with strong Guix hackers, it appears to me
>> that they missed the general concept of monad, at least it was vague.
>> Therefore, I tried to write a simple explanation,
>>
>> https://simon.tournier.info/posts/2021-02-03-monad.html
>
-- 
“In girum imus nocte et consumimur igni”

Re: Guix Documentation Meetup

[Katherine Cox-Buday]

Luis Felipe  writes:

> Hi,

Hello! Thank you for adding some context around why things are laid out the way 
they are.

I just wanted to respond again with gratitude for your work, and to plainly 
state that I view this work as difficult, with no clear best practice.

Sincerely,
-- 
Katherine

Re: Guix Documentation Meetup

[Luis Felipe]

Hi,

On Tuesday, December 14th, 2021 at 4:01 PM, Katherine Cox-Buday 
 wrote:

> Guile:
> 

> -   Tutorial for extending a C program with Guile
> -   The manual
> -   Scheme Resources
> -   "The Revised^6 Report on the Algorithmic Language Scheme"
> -   "" but 7
> -   "" but 5
> -   (more links that IMO are only meaningful if you already know Scheme)

For what it's worth, the intention with the structure of the Learn section was 
to put first introductory, prescriptive documentation about the language and 
what is possible to do with it. So:

+ Tutorials (Guides, etc.)
+ Reference manuals
+ Scheme resources

This documentation was supposed to fill some of the gaps that have been already 
mentioned in this thread and other previous conversations during the years in 
other channels. Unfortunately, the Tutorials section hasn't seen any additions 
since the day the website design was updated.

To me, the idea was to focus on building the Tutorials section gradually 
because, I thought, the reference and Scheme resources were relatively complete 
(except for the discoverability of SRFIs and how to use them in your own 
project when they don't come with Guile). I suggested something like this for 
tutorials:

+ Hello Guile: Getting Started (An overview of programming, and how to start 

with Guile)
+ Hello Guile: Let's develop a console application
+ Hello Guile: Let's develop a desktop application
+ Hello Guile: Let's develop a web application
+ Hello Guile: Let's develop a 2D game
+ Hello Guile: Let's package your software for distribution (with Guix)

I guess it is a matter of filling the blanks, which is a lot of work you have 
to enjoy doing and have enough time to do.

publickey - luis.felipe.la@protonmail.com - 0x12DE1598.asc
Description: application/pgp-keys


signature.asc
Description: OpenPGP digital signature

Re: Guix Documentation Meetup

[Katherine Cox-Buday]

Here is some analysis on various popular languages' documentation landing 
pages. I did this on Sunday, but I held it back from my previous message 
because it was already quite long, and I was worried this would be seen as 
over-critical and maybe raise the ire of various language fans.

But I think it might add to the conversation and help create better Guile 
documentation, so I'll risk it :)

For context, the only language on this list I really know well is Go.

Guile:
==
- Tutorial for extending a C program with Guile
- The manual
- Scheme Resources
  - "The Revised^6 Report on the Algorithmic Language Scheme"
  - "" but 7
  - "" but 5
  - (more links that IMO are only meaningful if you already know Scheme)

Overall, I'm left feeling like I have a clear sense of direction because it's 
apparent to me that I should click through to the reference manual. Experience 
with the GNU ecosystem helps here. I am left wondering whether I should click 
on any of the other links, and what I might be missing by not doing so. But 
clicking through reveals lengthy documents that I don't know if I should read 
yet or not.

Once I do click through to the manual, I am in a pretty familiar GNU document, 
and the other comments about this document become applicable.

The one thing I would add here is that other languages have a separate 
symbol/library explorer with a few more bells and whistles to support jumping 
around. It would be nice if Guile not only curated opinions on which modules to 
use, but used a separate, more featureful site for that.

Go (https://go.dev/doc/):
=
- A blurb trying to sell Go
- A link on how to install Go
- Links to tutorials and opinions on how to write Go.
- Links for very specific topics like editor plugins and fuzzing.

Overall, this seems cluttered and disorganized. For some reason there are 
several links to tutorials on very specific topics before there is a link to 
look at the packages in the standard library. These tutorials seem to be 
interspersed with more fundamental, important, beginner topics, and I'm not 
sure why.

The link to look at the documentation for the standard library -- something a 
developer will be working with a lot -- is titled "Package Documentation", too 
generic a term.

Once I do click through, there is a great site for navigating the standard 
library which explains what packages are for, and provides various navigation 
elements for jumping around.

Rust (https://www.rust-lang.org/learn):
===
- A link to a book
- A link to a course
- A link to rust by example
(note the support for 3 different kinds of learning styles)
- Core documentation
  - The standard library (here is, by way of being the standard library, an
opinion I can borrow for how things are done).
  - (more links I skipped because I don't know rust, and I"d start with the
above)

Overall, I am left feeling like I know where I would start depending on how I 
want to learn, and have a quick reference to the standard library's API.

Once I click through to the standard library, it suggests to me how to read it, 
and addresses the meta-question of what I'm looking at. I haven't used this 
site, but clicking around, it appears to have decent navigation elements for 
jumping around.

Python (https://www.python.org/doc/):
=
- A blurb on how the different ways to consume the documentation.
- Links grouped by self-reported expertise with the language

If I click on Beginner's guide:

- Link to explanation of what Python is
- Blurb on how to get Python
- Links for non-programmers to learn
- Links for programmers to learn
  - Acknowledgment that I've been reading wiki pages. I now have an
explanation for why what I've been reading feels cobbled together.
  - A link to a separate beginner's guide overview with more general
information about the language.
  - A long list of books, websites, and tutorials (note there is no opinion
given on which I should begin with)

Overall, I am left feeling overwhelmed, and like I must independently find a 
curated tutorial which will give me opinions I can use until I can form my own.

But wait! Had I clicked on "Python Docs" instead of "Beginner's Guide", I get 
something much easier to consume:

- A Tutorial which simply states "start here". As a newbie, OK!
  - This looks like a book
- Library reference
- Language reference
- General links to support usage

This is not overwhelming, and I feel like I have a small enough set of options 
to click through that I can find what I need. Further, it looks like a curated 
opinion of how I should do things, and in what order.

-- 
Katherine

Re: Guix Documentation Meetup

[Katherine Cox-Buday]

Blake Shaw  writes:

> Katherine Cox-Buday  writes:
>
> Katherine, reading a big deeper into your user experience report, its really
> so so helpful to have this concrete sort of step-by-step user experience
> report.

Definitely! The first step to resolution is a common understanding.

> Would you mind if I solicit the list for more reports like this for anyone
> who might feel like offering them?

I don't think I'm in a position to give you authority to do this, but I 
certainly don't mind :)

> And would you mind if I cite this in the presentation I'm gathering?

Not at all. I posted this to the public list for that reason.

Thanks for trying to take this on!

-- 
Katherine

Re: Guix Documentation Meetup

[Blake Shaw]

Katherine Cox-Buday  writes:

Katherine, reading a big deeper into your user experience report,
its really so so helpful to have this concrete sort of step-by-step
user experience report. Would you mind if I solicit the list
for more reports like this for anyone who might feel like offering them?
And would you mind if I cite this in the presentation I'm gathering?

-- 
“In girum imus nocte et consumimur igni”

Re: Guix Documentation Meetup

[Blake Shaw]

Katherine Cox-Buday  writes:

Katherine this is great material to chew on, much of which I can relate
to!  

-- 
“In girum imus nocte et consumimur igni”

Re: Guix Documentation Meetup

[Blake Shaw]

zimoun  writes:

Hi Simon, thanks for the input,
> Hi,
>
> On Sat, 11 Dec 2021 at 05:40, Blake Shaw 
> wrote:
>
>> --
>> tldr: is there also room to discuss contributing -- and possibly
>> doing a
>> sizeable makeover to -- the *Guile* documentation? If so, I could
>> give a
>> short 5 - 10 minutes presentation of what I think should be done (and
>> would volunteer to do).
>> --
>
> Cool!
>
> Minor comments trying to feed this worth proposal.
>
>> I don't know if this is the correct forum for it, but I personally
>> think
>> the biggest documentation obstacle in Guix at the moment isn't so much
>> in Guix, but instead in Guile. I found Guix via SICP & Racket about a
>> year ago, and I remained a happy Racket hacker until a couple months
>> ago
>> when I decided to devote my free time to learning Guile in hopes of
>> graduating to a Guix sensei one day.
>
> I agree that the learning path in Guile land is not always smooth.
> However, I do not think mastering Guile and/or its specificity is a
> requirement to be a “Guix sensei”.  Obviously, better Guile
> documentation improves the ecosystem, then it is an overall better. :-)

I mostly agree, and I used Guix for probably half a year before recently
deciding to dive into Guile seriously. But I still won't be able to,
say, write a `guix import` for a different package manager without
needing to spend ample time consulting the docs, bumping up against
confusions, etc. I want to get to the point that I'm able to take
on such matters with confidence, and so learning Guile seems important.   

>
>> While I've come to love Guile, compared to my experience with Racket
>> its
>> been quite burdensome for me to get in the hang of, something I
>> attribute
>> primarily to the structure of the docs, and not due to it being in any
>> way more difficult than Racket. While with Racket I was writing
>> useful programs in the standard #lang within my first week, with Guile
>> I often find that what should be almost trivial winds up with a lot of
>> time lost just trying to navigate and understand the docs. When I do
>> figure things out, it turns out to be no more difficult than the
>> equivalent
>> in Racket, but a lack of consistency in the path that leads there in
>> the
>> docs cause hangups, which has made trivial scripts that should take
>> an hour
>> become weekend projects.
>
> Well, I am not convinced it is because the structure of the docs.
> Instead, I think it is because it is missing docs. :-)
>
> If we compare apple to apple, here are the entry points:
>
> https://docs.racket-lang.org/
> https://www.gnu.org/software/guile/learn/
>
> and so the Guile manual
>
> https://www.gnu.org/software/guile/manual/guile.html
>
> is a reference manual, which correspond to, mainly
>
> https://docs.racket-lang.org/reference/
>
> and also,
>
> https://docs.racket-lang.org/guide/
>

I'm covering all this in a presentation I'll be putting together over
the coming weeks, including some visualization of the structure that I
think is helpful. I'd argue that `Hello Guix`, `Hello Scheme`,
`Programming in Scheme` and `Programming in C` serve a similar function
to `Quick`, `Continue` and `More` in the Racket docs.

> I am not convinced you started Racket by these ones. ;-)
>

I started with the Racket Guide! or really, with SICP and `#lang
sicp`, doing little bits of the Racket Guide along the way and that got
me interested in racket more generally.

But probably more importantly, I think like many programmers I
started writing little projects in Racket and read the docs along the
way. And thats where my analysis focuses: the documents should, and can,
be easier to navigate, allowing one to get in-and-out as needed, but
currently there are many related functions buried in disparate areas
usually without examples. Why FTW and POSIX in disparate parts of the
manual, things its obviously desirable to use in tandem? Why are there
multiple ways to do IO without a disclaimer as to which is prefered? If
there are 30 documented SRFIs, and most have only 1 or two sentences
written for most, but some contain a treasure trove of knowledge, many 
people will move on after linking into one or two SRFI entries and
forgoe the rest, and won't realize there are tranducers in guile.

All of this adds up to a fair amount of overhead imo, and I'm planning
to put together a report covering a structural analysis of it before the
end of the month.

> Indeed, one document on the Guile side vs two documents on Racket side;
> the Guile manual could be split, I do not know if the core issue here.
> Instead, IMHO, what is missing are all the others. :-) For instance,
>
> https://htdp.org/
>
> which is a really smooth introduction.  Somehow, it appears to me
> that it is missing an introduction, a similar document as,
>
>  https://www.gnu.org/software/emacs/manual/html_mono/eintr.html
>
I haven't read htdp, but its always at the top of recommendations
regarding Scheme literature (or PL 

Re: Guix Documentation Meetup

[zimoun]

Hi,

On Sat, 11 Dec 2021 at 05:40, Blake Shaw  wrote:

> --
> tldr: is there also room to discuss contributing -- and possibly doing a
> sizeable makeover to -- the *Guile* documentation? If so, I could give a
> short 5 - 10 minutes presentation of what I think should be done (and
> would volunteer to do).
> --

Cool!

Minor comments trying to feed this worth proposal.


> I don't know if this is the correct forum for it, but I personally think
> the biggest documentation obstacle in Guix at the moment isn't so much
> in Guix, but instead in Guile. I found Guix via SICP & Racket about a
> year ago, and I remained a happy Racket hacker until a couple months ago
> when I decided to devote my free time to learning Guile in hopes of
> graduating to a Guix sensei one day.

I agree that the learning path in Guile land is not always smooth.
However, I do not think mastering Guile and/or its specificity is a
requirement to be a “Guix sensei”.  Obviously, better Guile
documentation improves the ecosystem, then it is an overall better. :-)


> While I've come to love Guile, compared to my experience with Racket its
> been quite burdensome for me to get in the hang of, something I attribute
> primarily to the structure of the docs, and not due to it being in any
> way more difficult than Racket. While with Racket I was writing
> useful programs in the standard #lang within my first week, with Guile
> I often find that what should be almost trivial winds up with a lot of
> time lost just trying to navigate and understand the docs. When I do
> figure things out, it turns out to be no more difficult than the equivalent
> in Racket, but a lack of consistency in the path that leads there in the
> docs cause hangups, which has made trivial scripts that should take an hour
> become weekend projects.

Well, I am not convinced it is because the structure of the docs.
Instead, I think it is because it is missing docs. :-)

If we compare apple to apple, here are the entry points:

https://docs.racket-lang.org/
https://www.gnu.org/software/guile/learn/

and so the Guile manual

https://www.gnu.org/software/guile/manual/guile.html

is a reference manual, which correspond to, mainly

https://docs.racket-lang.org/reference/

and also,

https://docs.racket-lang.org/guide/

I am not convinced you started Racket by these ones. ;-)

Indeed, one document on the Guile side vs two documents on Racket side;
the Guile manual could be split, I do not know if the core issue here.
Instead, IMHO, what is missing are all the others. :-) For instance,

https://htdp.org/

which is a really smooth introduction.  Somehow, it appears to me
that it is missing an introduction, a similar document as,

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


> I know this isn't the Guile list, but when I've written on this topic in
> the IRC I've had no response, which make me think docs could be a
> bit of a bikeshedding topic in the community. But as Guile is
> fundamental to Guix and theres a lot of crossover btwn the communities,
> it seems like this could be a good time to raise these suggestions.

I agree.  For what it is worth, I tried once to quickly explain monad,
with the aim of “Store Monad“ in mind,

https://guix.gnu.org/manual/devel/en/guix.html#The-Store-Monad

After several discussions with strong Guix hackers, it appears to me
that they missed the general concept of monad, at least it was vague.
Therefore, I tried to write a simple explanation,

https://simon.tournier.info/posts/2021-02-03-monad.html

Bah, the other part has never seen the light, another story. :-)  Long
time ago, Pierre wrote down a quick introduction to Scheme, which ended
into the Cookbook,

https://guix.gnu.org/cookbook/en/guix-cookbook.html#Scheme-tutorials

>From my point of view, the missing documentation is the one between
newcomer and Reference manual.  For instance, setup a Guix/Guile
environment is not straightforward; Geiser helps, but even after some
time, I am often still fighting against it, and I do not know what
exists outside the Emacs world.


On the Guile land, one feature which really annoys me is the poor
discoverability from REPL; for an instance,

--8<---cut here---start->8---
$ guix repl
scheme@(guix-user)> ,a fold-packages
scheme@(guix-user)> ,use(gnu packages)
scheme@(guix-user)> ,a fold-packages
(gnu packages): fold-packages   #
scheme@(guix-user)> ,d fold-packages
Call (PROC PACKAGE RESULT) for each available package defined in one of
MODULES that matches SELECT?, using INIT as the initial value of RESULT.  It
is guaranteed to never traverse the same package twice.
--8<---cut here---end--->8---

well, IPython, GHCi, UTop (to name some I use) provide a complete
different experience.  Well, maybe resuming this discussion [1] is
worth.

1: 


> I've jotted down some notes on 

Re: Guix Documentation Meetup

[Katherine Cox-Buday]

Blake Shaw  writes:

> I'd love to know where you found trouble so that I can take that into
> consideration when developing a design strategy for the makeover.

When reading this, please keep in mind that I have a lot of gratitude for the 
various maintainers of this software and its respective documentation. 
Communication is very difficult, and relaying my experience and opinions is 
meant to convey that experience, and not to criticize anyone's efforts.

I think my frustration stems from the confluence of me not being familiar with 
scheme, how Guix writes scheme, how scheme the language and ecosystem work, the 
tools we have available to us, and then finally the documentation.

Not being a schemer (yet?), I can't speak with much authority, aside from the 
fact that I've written code in many languages, and most of these pain points 
are well addressed in others.

Usually, my frustrated workflow goes like this (warning: ignorance on display! 
:p):

- Identify something in Guix I want to do

- Open (or create) a file

- Start geiser

- Start writing Guile

- Come upon a semantic structure I want to write, and realize I don't know the
  Guile way to do it.
  
- In geiser, run =,a thing-i-want-to-look-for= (this is supposedly an apropos
  command that is supposed to search symbols for you). The command returns
  nothing. I realize I have to import the module implementing the thing I'm
  looking for first, thus defeating the purpose.

- Before, I would then go here[1] and try and textually search for the symbol.
  I have recently discovered the emacs function: =helm-info-guile= which makes
  searching a bit faster.

- Find that there are multiple, competing, modules which do the same thing in
  different ways.

- Realize I don't know which one to use, or which one Guix would prefer.

- Sometimes, realize that Guix has their own wrapper around one of the
  modules, and learn that something I thought was standard scheme is actually
  a Guix neologism.

- Import one and try it. Maybe import another and try it. Lose track of why
  I've imported things as I'm trying them because the module names have no
  indication of what they implement.

- Wish that Guix had a standard to prefix function calls with their module, as
  we do with =license:=.

- Have no way of automatically and programatically cleaning up imports to work
  around this.

- Forget what I was even trying to accomplish. Go to bed and try again
  tomorrow!

Specific to Guile documentation, I guess if I boil the above down, it would be 
something like:

Early in the documentation, directly address the intrinsic fragmentation of the 
scheme ecosystem, and how a new Guiler is meant to navigate that. Do so in 
terms that don't rely on experience with the Scheme ecosystem.

The Guile reference manual has this[2] section which, to me, is a paragraph 
which touches on this, and then much later has a blurb[3] on what SRFI is. I 
had no idea what =ice-9= was, and the first mention[5] of it in the manual is 
one of its modules. To my knowledge, what =ice-9= is, or why it's called that, 
is never addressed. It appears[5] I am not the first to be confused by this.

As a newcomer to Guile, and to scheme, I would expect Guile to give me its 
opinion of how to do things (i.e. which modules to prefer, what is considered 
"standard" in most schemes) until I've written enough Guile to form my own. As 
it's written, my impression is that the documentation relies on the reader 
knowing a lot about scheme coming in.

I feel there just needs to be an easier gradient for people trying to use Guile 
as their first scheme. It is not specifically Guile's problem, but as a service 
to its developers, the meta-topic should be addressed so a new developer is not 
left confused.

When we put a lot of work into something, it's really easy to fall in love with 
the idiosyncrasies of the thing, and to lose sight of what it's like to come 
into an ecosystem with no context. This can result in addressing things that 
feel important to us, the expert, but are really much further up the ladder of 
complexity.

When writing a landing page for a language, I feel the following is important:

*Don't overwhelm your newcomers.*
Your landing page should have few links, and they should directly address 
high-level questions:

- What am I looking at?
- How is what I'm looking at organized?
- What should people like me (e.g. non-programmers, programmers, schemers,
  people who don't speak English) be reading?
- A link to a site which provides easy to use symbol lookup.

The documentation can fan out in complexity from there, but the landing page 
must not be overwhelming.

Anyway, those are my opinions :)

[1] - https://www.gnu.org/software/guile/manual/guile.html
[2] - https://www.gnu.org/software/guile/manual/guile.html#Guile-Scheme
[3] - https://www.gnu.org/software/guile/manual/guile.html#SRFI-Support
[4] - https://www.gnu.org/software/guile/manual/guile.html#ice_002d9-optargs
[5] - 

Re: Guix Documentation Meetup

[Katherine Cox-Buday]

Ryan Prior  writes:

> I've found the Guile IRC channel to be polite and encouraging, but also very
> self-satisfied, which makes it hard to feel heard as a Guile hacker who's
> struggling.

Consider reaching out to Andy Wingo (wingo in IRC in #guile). I hope I am not 
laying this issue at his feet by suggesting this, but I have interacted with 
him a handful of times, and he is a genuinely nice and helpful person, and also 
a guile maintainer. I am pretty confident he would want to help make this 
problem better -- especially if there are those willing to do some work.

Good luck! I have also found myself hunting around for basic functionality, and 
not being a guiler, nor even a schemer (I love lisps, but I mostly write 
emacs-lisp and common-lisp), wondering why things are fragmented into weird 
modules. It's a shame, because I feel like I would be contributing bigger 
features to Guix if I could stop bouncing off the language.

-- 
Katherine

Re: Guix Documentation Meetup

[Blake Shaw]

Ryan Prior  writes:

> Absolutely. The Guile docs are unusable and make Guile a pain to work
> with. I say this as an experienced lisp & scheme user with decades of
> experience now in elisp, racket, and clojure. 

oh good, I'm glad to hear that I'm not alone! to be honest I don't think
its *so* bad, but it certainly demands a the user of suffers a bit, which
makes Guix in general a more difficult sell. And Guile is a truly
impressive programming language; its docs are just in need of some
remodeling I think. 

> I've found the Guile IRC channel to be polite and encouraging, but
> also very self-satisfied, which makes it hard to feel heard as a Guile
> hacker who's struggling. I hesitate to tackle any kind of nontrivial

I first checked it out when I began learning about guix, and it
seemed quite friendly. but unfortunately since I started studying Guile
I haven't had any of my questions there responded to. hopefully all is
ok. 

> problem with Guile because I have no confidence I will find tools that
> save me time; I'm proficient with a half dozen other languages,
> including multiple lisps, which provide much better support. So even
> though I really want to learn Guile,because of Guix, Shepherd and
> other cool software written in it, I'm no more likely to choose Guile
> for a software project today than I was 3 years ago when I just
> started learning it.

As long as it doesn't stall out into bikeshedding and the community is
supportive I'm dedicated to this project of working on Guile's docs
while I become acquainted with its depths. As a media artist theres
really a lot it offers. But like you say, it can suck up time with little
return; trying to figure out certain basic things in Guile has made C
feel like Python at times. Luckily, the C interface is decently
documented.

>
> When I talk to experienced hackers in the Guile community I get the
> sense they've just accepted that yeah, the only way to get anywhere is
> to cold memorize the most popular ~80 SRFIs or implement everything
> you need yourself. One person I talked to was like "oh yeah Guile's
> great, you just have to implement your own standard library like I
> did."

I'd be interested to hear any anecdotes regarding whether restructuring
the docs was attempted in the past, and what problems it incurred.
Considering my background in academia, writing is second nature, and
this has been the only thing in Guix that has appeared to me as a
serious pain point, so if I'm the only one who doesn't find writing docs
insufferable, I'm happy to take on that task for the time being.

But again, it depends on whether the community will grant me their
confidence. 

> I'd love to hear your talk, if you're up to present at the Guix meetup
> I'll definitely come and listen. I'm also happy to do what I can to
> help drive Guile adoption, create a great learning experience around
> it, and finally start to build the language community that Guile is
> lacking.

Awesome! Me too! It's seriously an incredible language -- it's just lacking
a consistent, ergonomic presentation atm. But even without that, it's
the fastest-booting lisp I've tried, and already thats enough to keep me
from crawling back to Racket (which might boot fast now with CS, but I
haven't checked in lately)

As it currently stands, its better to ditch the docs and just browse
the code base. And while for some that might be like reading email,
for the vast majority thats demanding some serious overhead from users
who are likely to pick up Guile for their personal, off-hours, creative
work.

It won't be a talk, just a 5-10min presentation of some notes where I'll
try to provide a light analysis of a few problems, along with how I
would go about fixing them, and then if all agree I'll get to work on
it.

Thanks for the encouragement!

ez,
b
-- 
“In girum imus nocte et consumimur igni”

Re: Guix Documentation Meetup

[Ryan Prior]

‐‐‐ Original Message ‐‐‐

On Friday, December 10th, 2021 at 10:40 PM, Blake Shaw 
 wrote:

> tldr: is there also room to discuss contributing -- and possibly doing a 
> sizeable makeover to -- the Guile documentation?

Absolutely. The Guile docs are unusable and make Guile a pain to work with. I 
say this as an experienced lisp & scheme user with decades of experience now in 
elisp, racket, and clojure. After bouncing off of guile projects for years, 
last November I decided to do Advent of Code in Guile to force myself to 
finally get the hang of it & get productive. I gave up after a week, every task 
was unpleasant and I was reinventing basic language features because I couldn't 
find out where/if they were implemented in some obscure SRFI or ice-9 module. 
Like you wrote, the code I'd finally end up was fine, the language itself seems 
nice, but it's just plain inaccessible.

I've found the Guile IRC channel to be polite and encouraging, but also very 
self-satisfied, which makes it hard to feel heard as a Guile hacker who's 
struggling. I hesitate to tackle any kind of nontrivial problem with Guile 
because I have no confidence I will find tools that save me time; I'm 
proficient with a half dozen other languages, including multiple lisps, which 
provide much better support. So even though I really want to learn 
Guile,because of Guix, Shepherd and other cool software written in it, I'm no 
more likely to choose Guile for a software project today than I was 3 years ago 
when I just started learning it.

When I talk to experienced hackers in the Guile community I get the sense 
they've just accepted that yeah, the only way to get anywhere is to cold 
memorize the most popular ~80 SRFIs or implement everything you need yourself. 
One person I talked to was like "oh yeah Guile's great, you just have to 
implement your own standard library like I did."

I'd love to hear your talk, if you're up to present at the Guix meetup I'll 
definitely come and listen. I'm also happy to do what I can to help drive Guile 
adoption, create a great learning experience around it, and finally start to 
build the language community that Guile is lacking.

Cheers,
Ryan

Re: Guix Documentation Meetup

[Blake Shaw]

hiya guix,

@cybersyn from IRC here, I recently contributed my first package, [notcurses]

--
tldr: is there also room to discuss contributing -- and possibly doing a
sizeable makeover to -- the *Guile* documentation? If so, I could give a
short 5 - 10 minutes presentation of what I think should be done (and
would volunteer to do).
--

I think I can personally offer a lot in terms of contributing to
documentation. While I don't serious experience w/technical writing,
prior to the pandemic I was doing my PhD in philosophy of mathematics,
so I come from a cross-disciplinary background that involves the often
difficult area of communicating new, formal ideas to previously
unexposed readers. I've also made a living as a new media artist since
2009, working mostly in C and C++ based frameworks, so I also have some
knowledge of the difficulties "crafters" have when learning new
development systems.

I don't know if this is the correct forum for it, but I personally think
the biggest documentation obstacle in Guix at the moment isn't so much
in Guix, but instead in Guile. I found Guix via SICP & Racket about a
year ago, and I remained a happy Racket hacker until a couple months ago
when I decided to devote my free time to learning Guile in hopes of
graduating to a Guix sensei one day.

While I've come to love Guile, compared to my experience with Racket its
been quite burdensome for me to get in the hang of, something I attribute
primarily to the structure of the docs, and not due to it being in any
way more difficult than Racket. While with Racket I was writing
useful programs in the standard #lang within my first week, with Guile
I often find that what should be almost trivial winds up with a lot of
time lost just trying to navigate and understand the docs. When I do
figure things out, it turns out to be no more difficult than the equivalent
in Racket, but a lack of consistency in the path that leads there in the
docs cause hangups, which has made trivial scripts that should take an hour
become weekend projects.

I know this isn't the Guile list, but when I've written on this topic in
the IRC I've had no response, which make me think docs could be a
bit of a bikeshedding topic in the community. But as Guile is
fundamental to Guix and theres a lot of crossover btwn the communities,
it seems like this could be a good time to raise these suggestions.

I've jotted down some notes on several concrete examples of where the docs
diverge from stylistic consistency, as well as some light analysis as to
why such seemingly small inconsistencies can lead to such hangups in the 
learning
process. If folks would be interested in me presenting a short 5-10min
presentation of these notes, I'd be happy to share.

Sorry for such a long-winded message! Personally, good documentation is
absolutely essential, and I feel like I could give Guile's docs a
serious makeover while I'm still at the early stage of my plunge and
have a perspective on the psychology of not-understanding -- something
that won't last long!

ez,
blake

-- 
“In girum imus nocte et consumimur igni”