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”