Re: Guix Documentation Meetup

[Blake Shaw <blake@nonconstructivism.com>]

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”