* Re: Guix Documentation Meetup
@ 2021-12-10 22:40 Blake Shaw
2021-12-10 23:18 ` Ryan Prior
` (3 more replies)
0 siblings, 4 replies; 51+ messages in thread
From: Blake Shaw @ 2021-12-10 22:40 UTC (permalink / raw)
To: jgart; +Cc: Guix Devel
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”
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2021-12-10 22:40 Guix Documentation Meetup Blake Shaw
@ 2021-12-10 23:18 ` Ryan Prior
2021-12-11 18:55 ` Katherine Cox-Buday
2021-12-13 8:29 ` zimoun
` (2 subsequent siblings)
3 siblings, 1 reply; 51+ messages in thread
From: Ryan Prior @ 2021-12-10 23:18 UTC (permalink / raw)
To: Blake Shaw; +Cc: jgart, Guix Devel
‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Friday, December 10th, 2021 at 10:40 PM, Blake Shaw <blake@nonconstructivism.com> 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
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2021-12-10 23:18 ` Ryan Prior
@ 2021-12-11 18:55 ` Katherine Cox-Buday
[not found] ` <87lf0q2m7n.fsf@nonconstructivism.com>
0 siblings, 1 reply; 51+ messages in thread
From: Katherine Cox-Buday @ 2021-12-11 18:55 UTC (permalink / raw)
To: Ryan Prior; +Cc: Guix Devel, jgart
Ryan Prior <rprior@protonmail.com> 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
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2021-12-10 22:40 Guix Documentation Meetup Blake Shaw
2021-12-10 23:18 ` Ryan Prior
@ 2021-12-13 8:29 ` zimoun
2021-12-14 16:01 ` Katherine Cox-Buday
2021-12-20 17:45 ` Guile documentation Ludovic Courtès
2021-12-21 6:41 ` Guix Documentation Meetup adriano
3 siblings, 1 reply; 51+ messages in thread
From: zimoun @ 2021-12-13 8:29 UTC (permalink / raw)
To: Blake Shaw, jgart; +Cc: Guix Devel
Hi,
On Sat, 11 Dec 2021 at 05:40, Blake Shaw <blake@nonconstructivism.com> 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 #<procedure fold-packages (proc init #:optional modules #:key select?)>
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: <https://yhetil.org/guix/86d00evkmr.fsf@gmail.com/>
> 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.
I would be interested to listen your ideas, here, there or overthere. :-)
Cheers,
simon
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2021-12-13 8:29 ` zimoun
@ 2021-12-14 16:01 ` Katherine Cox-Buday
2021-12-14 17:38 ` Luis Felipe
0 siblings, 1 reply; 51+ messages in thread
From: Katherine Cox-Buday @ 2021-12-14 16:01 UTC (permalink / raw)
To: zimoun; +Cc: Guix Devel, jgart
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
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2021-12-14 16:01 ` Katherine Cox-Buday
@ 2021-12-14 17:38 ` Luis Felipe
2021-12-14 17:52 ` Katherine Cox-Buday
0 siblings, 1 reply; 51+ messages in thread
From: Luis Felipe @ 2021-12-14 17:38 UTC (permalink / raw)
To: Katherine Cox-Buday; +Cc: zimoun, Guix Devel, jgart
[-- Attachment #1.1: Type: text/plain, Size: 1762 bytes --]
Hi,
On Tuesday, December 14th, 2021 at 4:01 PM, Katherine Cox-Buday <cox.katherine.e@gmail.com> 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.
[-- Attachment #1.2: publickey - luis.felipe.la@protonmail.com - 0x12DE1598.asc --]
[-- Type: application/pgp-keys, Size: 1815 bytes --]
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 509 bytes --]
^ permalink raw reply [flat|nested] 51+ messages in thread
* Guile documentation
2021-12-10 22:40 Guix Documentation Meetup Blake Shaw
2021-12-10 23:18 ` Ryan Prior
2021-12-13 8:29 ` zimoun
@ 2021-12-20 17:45 ` Ludovic Courtès
2021-12-21 11:01 ` Blake Shaw
2021-12-21 6:41 ` Guix Documentation Meetup adriano
3 siblings, 1 reply; 51+ messages in thread
From: Ludovic Courtès @ 2021-12-20 17:45 UTC (permalink / raw)
To: Blake Shaw; +Cc: Guix Devel, jgart
Hi Blake,
Blake Shaw <blake@nonconstructivism.com> skribis:
> 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.
IWBN if we could take advantage of your fresh eye to restructure the
Guile manual in a way that makes it more convenient.
Guile has changed a lot since the manual was initially written, a lot of
sections were added, some removed, but we probably didn’t take the time
to sit down and see how to restructure it accordingly.
So if you have a specific structure in mind, or if you remember
precisely what was hard to find and located in a unexpected section,
please let’s take advantage of that!
Thanks,
Ludo’.
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guile documentation
2021-12-20 17:45 ` Guile documentation Ludovic Courtès
@ 2021-12-21 11:01 ` Blake Shaw
0 siblings, 0 replies; 51+ messages in thread
From: Blake Shaw @ 2021-12-21 11:01 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: Guix Devel, jgart
[-- Attachment #1: Type: text/plain, Size: 2018 bytes --]
Hi Ludo,
(replying to this email from my other email address because I can't seem to
find it in gnus, which I only recently switched to)
For sure. I'm preparing a little document that provides an analysis of pain
points in the docs, which I'll hopefully have done by the end of this week
and can send to the group. I'll be mostly focused on the general
organizational structure of the docs and will offer solutions that if
everyone agrees to I'll go ahead and start putting to work.
Ez,
Blake
On Tue, Dec 21, 2021, 01:57 Ludovic Courtès <ludo@gnu.org> wrote:
> Hi Blake,
>
> Blake Shaw <blake@nonconstructivism.com> skribis:
>
> > 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.
>
> IWBN if we could take advantage of your fresh eye to restructure the
> Guile manual in a way that makes it more convenient.
>
> Guile has changed a lot since the manual was initially written, a lot of
> sections were added, some removed, but we probably didn’t take the time
> to sit down and see how to restructure it accordingly.
>
> So if you have a specific structure in mind, or if you remember
> precisely what was hard to find and located in a unexpected section,
> please let’s take advantage of that!
>
> Thanks,
> Ludo’.
>
>
[-- Attachment #2: Type: text/html, Size: 2622 bytes --]
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2021-12-10 22:40 Guix Documentation Meetup Blake Shaw
` (2 preceding siblings ...)
2021-12-20 17:45 ` Guile documentation Ludovic Courtès
@ 2021-12-21 6:41 ` adriano
3 siblings, 0 replies; 51+ messages in thread
From: adriano @ 2021-12-21 6:41 UTC (permalink / raw)
To: Blake Shaw, jgart; +Cc: Guix Devel
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 pleeeease !!!
> 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!
Oh God, did you give this talk ?
Is a recordng available ?
If it's not, you should make a vlog !
Please !
>
> ez,
> blake
>
^ permalink raw reply [flat|nested] 51+ messages in thread
* Guix Documentation Meetup
@ 2022-03-10 17:02 Raghav Gururajan
2022-03-10 17:11 ` Raghav Gururajan
0 siblings, 1 reply; 51+ messages in thread
From: Raghav Gururajan @ 2022-03-10 17:02 UTC (permalink / raw)
To: guix-devel; +Cc: jgart
[-- Attachment #1.1: Type: text/plain, Size: 588 bytes --]
Hello Guix!
WhereIsEveryone community is hosting a meetup regarding documentation in
Guix.
We'll be discussing and/or working on; adding new contents, removing
obsolete contents and improving contents where required. We can also
look into current documentation style/model and generate
feedback/suggestions. The documentation can pertain to manual or
cookbook or prospective wiki. The outcome of the meetup will be
recorded, organized and sent to Guix upstream.
DATE: Saturday, March 19, 2022.
TIME: 15:00 UTC
Duration: ~1.5hrs
Regards,
Raghav "RG" Gururajan.
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 236 bytes --]
^ permalink raw reply [flat|nested] 51+ messages in thread
[parent not found: <mailman.34870.1641617883.18145.guix-devel@gnu.org>]
* Re: Guix Documentation Meetup
[not found] <mailman.34870.1641617883.18145.guix-devel@gnu.org>
@ 2022-01-08 8:42 ` calcium
2022-01-08 11:35 ` Ricardo Wurmus
2022-01-08 13:41 ` Matt
0 siblings, 2 replies; 51+ messages in thread
From: calcium @ 2022-01-08 8:42 UTC (permalink / raw)
To: matt; +Cc: guix-devel
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/ ).
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-08 8:42 ` calcium
@ 2022-01-08 11:35 ` Ricardo Wurmus
2022-01-08 11:49 ` calcium
2022-01-08 16:24 ` Matt
2022-01-08 13:41 ` Matt
1 sibling, 2 replies; 51+ messages in thread
From: Ricardo Wurmus @ 2022-01-08 11:35 UTC (permalink / raw)
To: calcium; +Cc: guix-devel
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
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-08 11:35 ` Ricardo Wurmus
@ 2022-01-08 11:49 ` calcium
2022-01-08 16:24 ` Matt
1 sibling, 0 replies; 51+ messages in thread
From: calcium @ 2022-01-08 11:49 UTC (permalink / raw)
To: Ricardo Wurmus; +Cc: guix-devel
>> 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)
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-08 11:35 ` Ricardo Wurmus
2022-01-08 11:49 ` calcium
@ 2022-01-08 16:24 ` Matt
2022-01-08 18:58 ` Ricardo Wurmus
` (2 more replies)
1 sibling, 3 replies; 51+ messages in thread
From: Matt @ 2022-01-08 16:24 UTC (permalink / raw)
To: Ricardo Wurmus; +Cc: guix-devel, 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.
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).
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-08 16:24 ` Matt
@ 2022-01-08 18:58 ` Ricardo Wurmus
2022-01-08 19:06 ` Leo Famulari
2022-01-13 0:22 ` Leo Famulari
2 siblings, 0 replies; 51+ messages in thread
From: Ricardo Wurmus @ 2022-01-08 18:58 UTC (permalink / raw)
To: Matt; +Cc: guix-devel, calcium
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
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-08 16:24 ` Matt
2022-01-08 18:58 ` Ricardo Wurmus
@ 2022-01-08 19:06 ` Leo Famulari
2022-01-09 21:12 ` Matt
2022-01-13 0:22 ` Leo Famulari
2 siblings, 1 reply; 51+ messages in thread
From: Leo Famulari @ 2022-01-08 19:06 UTC (permalink / raw)
To: Matt; +Cc: guix-devel, calcium
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.
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-08 19:06 ` Leo Famulari
@ 2022-01-09 21:12 ` Matt
2022-01-10 9:05 ` André A. Gomes
2022-01-12 18:41 ` Leo Famulari
0 siblings, 2 replies; 51+ messages in thread
From: Matt @ 2022-01-09 21:12 UTC (permalink / raw)
To: guix-devel; +Cc: calcium
> 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.
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-09 21:12 ` Matt
@ 2022-01-10 9:05 ` André A. Gomes
2022-01-10 13:40 ` Matt
2022-01-12 18:41 ` Leo Famulari
1 sibling, 1 reply; 51+ messages in thread
From: André A. Gomes @ 2022-01-10 9:05 UTC (permalink / raw)
To: Matt; +Cc: guix-devel, calcium
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"
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-10 9:05 ` André A. Gomes
@ 2022-01-10 13:40 ` Matt
2022-01-10 16:05 ` André A. Gomes
0 siblings, 1 reply; 51+ messages in thread
From: Matt @ 2022-01-10 13:40 UTC (permalink / raw)
To: "André A. Gomes"; +Cc: guix-devel, calcium
> 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.
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-10 13:40 ` Matt
@ 2022-01-10 16:05 ` André A. Gomes
2022-01-11 18:45 ` Matt
0 siblings, 1 reply; 51+ messages in thread
From: André A. Gomes @ 2022-01-10 16:05 UTC (permalink / raw)
To: Matt; +Cc: guix-devel, calcium
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"
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-10 16:05 ` André A. Gomes
@ 2022-01-11 18:45 ` Matt
0 siblings, 0 replies; 51+ messages in thread
From: Matt @ 2022-01-11 18:45 UTC (permalink / raw)
To: "André A. Gomes"; +Cc: guix-devel, calcium
> 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.
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-09 21:12 ` Matt
2022-01-10 9:05 ` André A. Gomes
@ 2022-01-12 18:41 ` Leo Famulari
2022-01-13 0:04 ` Matt
1 sibling, 1 reply; 51+ messages in thread
From: Leo Famulari @ 2022-01-12 18:41 UTC (permalink / raw)
To: Matt; +Cc: guix-devel, calcium
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.
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-12 18:41 ` Leo Famulari
@ 2022-01-13 0:04 ` Matt
0 siblings, 0 replies; 51+ messages in thread
From: Matt @ 2022-01-13 0:04 UTC (permalink / raw)
To: Leo Famulari; +Cc: guix-devel, calcium
---- 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.
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-08 16:24 ` Matt
2022-01-08 18:58 ` Ricardo Wurmus
2022-01-08 19:06 ` Leo Famulari
@ 2022-01-13 0:22 ` Leo Famulari
2022-01-13 13:15 ` ilmu
2 siblings, 1 reply; 51+ messages in thread
From: Leo Famulari @ 2022-01-13 0:22 UTC (permalink / raw)
To: Matt; +Cc: guix-devel, calcium
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.
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-08 8:42 ` calcium
2022-01-08 11:35 ` Ricardo Wurmus
@ 2022-01-08 13:41 ` Matt
2022-01-08 14:09 ` Julien Lepiller
2022-01-08 14:39 ` Josselin Poiret
1 sibling, 2 replies; 51+ messages in thread
From: Matt @ 2022-01-08 13:41 UTC (permalink / raw)
To: calcium; +Cc: guix-devel
> 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?
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-08 13:41 ` Matt
@ 2022-01-08 14:09 ` Julien Lepiller
2022-01-08 14:54 ` Matt
2022-01-08 14:39 ` Josselin Poiret
1 sibling, 1 reply; 51+ messages in thread
From: Julien Lepiller @ 2022-01-08 14:09 UTC (permalink / raw)
To: guix-devel, Matt, calcium; +Cc: guix-devel
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.
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-08 13:41 ` Matt
2022-01-08 14:09 ` Julien Lepiller
@ 2022-01-08 14:39 ` Josselin Poiret
1 sibling, 0 replies; 51+ messages in thread
From: Josselin Poiret @ 2022-01-08 14:39 UTC (permalink / raw)
To: Matt, calcium; +Cc: guix-devel
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
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
@ 2022-01-08 4:52 Matt
2022-01-10 9:47 ` Oliver Propst
0 siblings, 1 reply; 51+ messages in thread
From: Matt @ 2022-01-08 4:52 UTC (permalink / raw)
To: jgart; +Cc: guix-devel
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 is strained.
The documentation trilemma is:
Intelligible, comprehensive, and discoverable: Pick two.
I feel Guix does pretty well on being comprehensive. And, despite some rough spots, it's largely intelligible.
Guix fails for me on discoverablity. Can I quickly find the answer to my question *and know that I've found it?* That's why I think defining terms, focusing on their significance, and providing context through workflows can help.
Discoverablity is also a technical problem. I want a C-h f for Guix. That's something I think Guix and it's community is well positioned to solve, what with all these reproducible environments, Emacs users, and what not. I'd love to help that come to fruition.
I can write and publish all day on my blog, but if it's not discoverable and, more importantly, not correct, it's not helping anyone. I, and people like me, need help from experts. That's why I'm so excited about this meet up. I know I can string some words together enough to be understandable. But is what I'm saying helpful?
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? 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.
Sometimes I wonder why I'm choosing to struggle to learn Guix. The reason I choose to persevere is that Guix could be like Emacs, software for a lifetime. That's something I'm willing to invest in.
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-08 4:52 Matt
@ 2022-01-10 9:47 ` Oliver Propst
2022-01-10 13:15 ` Matt
0 siblings, 1 reply; 51+ messages in thread
From: Oliver Propst @ 2022-01-10 9:47 UTC (permalink / raw)
To: Matt; +Cc: guix-devel, jgart
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 :)
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-10 9:47 ` Oliver Propst
@ 2022-01-10 13:15 ` Matt
2022-01-11 16:24 ` jgart
0 siblings, 1 reply; 51+ messages in thread
From: Matt @ 2022-01-10 13:15 UTC (permalink / raw)
To: Oliver Propst; +Cc: guix-devel, jgart
> 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.
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-10 13:15 ` Matt
@ 2022-01-11 16:24 ` jgart
2022-01-12 0:59 ` Matt
0 siblings, 1 reply; 51+ messages in thread
From: jgart @ 2022-01-11 16:24 UTC (permalink / raw)
To: Matt; +Cc: Oliver Propst, guix-devel
On Mon, 10 Jan 2022 08:15:34 -0500 Matt <matt@excalamus.com> 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
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-11 16:24 ` jgart
@ 2022-01-12 0:59 ` Matt
2022-01-12 1:20 ` jgart
0 siblings, 1 reply; 51+ messages in thread
From: Matt @ 2022-01-12 0:59 UTC (permalink / raw)
To: jgart; +Cc: guix-devel
---- On Tue, 11 Jan 2022 11:24:20 -0500 jgart <jgart@dismail.de> 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.
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2022-01-12 0:59 ` Matt
@ 2022-01-12 1:20 ` jgart
2022-01-12 2:57 ` Matt
0 siblings, 1 reply; 51+ messages in thread
From: jgart @ 2022-01-12 1:20 UTC (permalink / raw)
To: Matt; +Cc: Oliver Propst, guix-devel
On Tue, 11 Jan 2022 19:59:37 -0500 Matt <matt@excalamus.com> wrote:
> ---- On Tue, 11 Jan 2022 11:24:20 -0500 jgart <jgart@dismail.de> 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/guixrus@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/
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
@ 2021-12-13 13:45 Blake Shaw
2021-12-13 15:55 ` Katherine Cox-Buday
0 siblings, 1 reply; 51+ messages in thread
From: Blake Shaw @ 2021-12-13 13:45 UTC (permalink / raw)
To: Katherine Cox-Buday; +Cc: Guix Devel
Katherine Cox-Buday <cox.katherine.e@gmail.com> 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”
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2021-12-13 13:45 Blake Shaw
@ 2021-12-13 15:55 ` Katherine Cox-Buday
0 siblings, 0 replies; 51+ messages in thread
From: Katherine Cox-Buday @ 2021-12-13 15:55 UTC (permalink / raw)
To: Blake Shaw; +Cc: Guix Devel
Blake Shaw <blake@nonconstructivism.com> writes:
> Katherine Cox-Buday <cox.katherine.e@gmail.com> 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
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
@ 2021-12-13 12:41 Blake Shaw
0 siblings, 0 replies; 51+ messages in thread
From: Blake Shaw @ 2021-12-13 12:41 UTC (permalink / raw)
To: Katherine Cox-Buday; +Cc: Guix Devel
Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:
Katherine this is great material to chew on, much of which I can relate
to!
--
“In girum imus nocte et consumimur igni”
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
@ 2021-12-13 12:33 Blake Shaw
2021-12-15 17:37 ` Blake Shaw
0 siblings, 1 reply; 51+ messages in thread
From: Blake Shaw @ 2021-12-13 12:33 UTC (permalink / raw)
To: zimoun; +Cc: jgart, Guix Devel
zimoun <zimon.toutoune@gmail.com> writes:
Hi Simon, thanks for the input,
> Hi,
>
> On Sat, 11 Dec 2021 at 05:40, Blake Shaw <blake@nonconstructivism.com>
> 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 in general). I mean, Scheme in
general has better book-length literature than possibly any other
language! Dybvig's The Scheme Programming Language has been the most
helpful, but still, it doesn't tell me anything about GOOPs, Guile's
compiler infrastructure, Tree-IL, CPS soup, etc.
but I guess my point it, those are canonical works by some of our finest
wizards. If someone can bring that degree of pedagogical pedigree to the
Guix ecosystem we will certainly be blessed. But I think what I can
personally offer is to work on refactoring what currently exists.
>> 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
nice, I look forward to checking this out! yet another monad tutorial is
always due for those of us who never ventured far down that path.
>
> 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.
>
Yeah, I agree. We need a "More Perfect Setup" for hacking on Guix! In
particular, I think it would be helpful to add a section showing how to
jump to definitions emacs style; thats probably been the most helpful
tool for learning, personally.
> On the Guile land, one feature which really annoys me is the poor
> discoverability from REPL; for an instance,
>
> $ guix repl
> scheme@(guix-user)> ,a fold-packages
> scheme@(guix-user)> ,use(gnu packages)
> scheme@(guix-user)> ,a fold-packages
> (gnu packages): fold-packages #<procedure fold-packages (proc init #:optional modules #:key select?)>
> 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.
oh interesting, I didn't know that it sometimes will fail to find a
package. in general, I'm a big fan of definitions in the repl. the less
I have to look away from my text editor, the better. this is certainly
smthng that could be improved.
>
> well, IPython, GHCi, UTop (to name some I use) provide a complete
> different experience. Well, maybe resuming this discussion [1] is
> worth.
>
> 1: <https://yhetil.org/guix/86d00evkmr.fsf@gmail.com/>
>
>> 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.
>
> I would be interested to listen your ideas, here, there or
> overthere. :-)
>
> Cheers,
> simon
>
>
thanks for the feedback! looking forward to keeping it going.
blake
--
“In girum imus nocte et consumimur igni”
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2021-12-13 12:33 Blake Shaw
@ 2021-12-15 17:37 ` Blake Shaw
2021-12-15 19:12 ` zimoun
0 siblings, 1 reply; 51+ messages in thread
From: Blake Shaw @ 2021-12-15 17:37 UTC (permalink / raw)
To: zimoun; +Cc: jgart, Guix Devel
Blake Shaw <blake@nonconstructivism.com> 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”
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
2021-12-15 17:37 ` Blake Shaw
@ 2021-12-15 19:12 ` zimoun
2021-12-15 22:37 ` jgart
0 siblings, 1 reply; 51+ messages in thread
From: zimoun @ 2021-12-15 19:12 UTC (permalink / raw)
To: zimoun, jgart, Guix Devel
Hi,
On Wed, 15 Dec 2021 at 18:37, Blake Shaw <blake@nonconstructivism.com> wrote:
>
> Blake Shaw <blake@nonconstructivism.com> 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
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: Guix Documentation Meetup
@ 2021-12-11 1:42 Blake Shaw
0 siblings, 0 replies; 51+ messages in thread
From: Blake Shaw @ 2021-12-11 1:42 UTC (permalink / raw)
To: Ryan Prior; +Cc: jgart, Guix Devel
Ryan Prior <rprior@protonmail.com> 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”
^ permalink raw reply [flat|nested] 51+ messages in thread
* Guix Documentation Meetup
@ 2021-12-09 9:28 jgart
0 siblings, 0 replies; 51+ messages in thread
From: jgart @ 2021-12-09 9:28 UTC (permalink / raw)
To: Guix Devel
Hi Guixers,
I wanted to announce that this Sunday, December 12, we'll be meeting over
Big Blue Button to work on Guix Documentation.
The meetup will start at 10:30 AM ET.
https://meet.nixnet.services/b/jga-rtw-ahw-yky
Hope to see you there,
jgart
^ permalink raw reply [flat|nested] 51+ messages in thread
end of thread, other threads:[~2022-03-10 17:12 UTC | newest]
Thread overview: 51+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2021-12-10 22:40 Guix Documentation Meetup Blake Shaw
2021-12-10 23:18 ` Ryan Prior
2021-12-11 18:55 ` Katherine Cox-Buday
[not found] ` <87lf0q2m7n.fsf@nonconstructivism.com>
2021-12-13 3:50 ` Katherine Cox-Buday
2021-12-30 21:52 ` adriano
2022-01-06 15:58 ` Katherine Cox-Buday
2021-12-13 8:29 ` zimoun
2021-12-14 16:01 ` Katherine Cox-Buday
2021-12-14 17:38 ` Luis Felipe
2021-12-14 17:52 ` Katherine Cox-Buday
2021-12-20 17:45 ` Guile documentation Ludovic Courtès
2021-12-21 11:01 ` Blake Shaw
2021-12-21 6:41 ` Guix Documentation Meetup adriano
-- strict thread matches above, loose matches on Subject: below --
2022-03-10 17:02 Raghav Gururajan
2022-03-10 17:11 ` Raghav Gururajan
[not found] <mailman.34870.1641617883.18145.guix-devel@gnu.org>
2022-01-08 8:42 ` calcium
2022-01-08 11:35 ` Ricardo Wurmus
2022-01-08 11:49 ` calcium
2022-01-08 16:24 ` Matt
2022-01-08 18:58 ` Ricardo Wurmus
2022-01-08 19:06 ` Leo Famulari
2022-01-09 21:12 ` Matt
2022-01-10 9:05 ` André A. Gomes
2022-01-10 13:40 ` Matt
2022-01-10 16:05 ` André A. Gomes
2022-01-11 18:45 ` Matt
2022-01-12 18:41 ` Leo Famulari
2022-01-13 0:04 ` Matt
2022-01-13 0:22 ` Leo Famulari
2022-01-13 13:15 ` ilmu
2022-01-08 13:41 ` Matt
2022-01-08 14:09 ` Julien Lepiller
2022-01-08 14:54 ` Matt
2022-01-08 14:39 ` Josselin Poiret
2022-01-08 4:52 Matt
2022-01-10 9:47 ` Oliver Propst
2022-01-10 13:15 ` Matt
2022-01-11 16:24 ` jgart
2022-01-12 0:59 ` Matt
2022-01-12 1:20 ` jgart
2022-01-12 2:57 ` Matt
2022-01-12 3:10 ` Matt
2021-12-13 13:45 Blake Shaw
2021-12-13 15:55 ` Katherine Cox-Buday
2021-12-13 12:41 Blake Shaw
2021-12-13 12:33 Blake Shaw
2021-12-15 17:37 ` Blake Shaw
2021-12-15 19:12 ` zimoun
2021-12-15 22:37 ` jgart
2021-12-11 1:42 Blake Shaw
2021-12-09 9:28 jgart
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).