Re: Guix Documentation Meetup

[adriano <randomlooser@riseup.net>]

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
>