Re: Guix Documentation Meetup

[Blake Shaw]

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”