Re: Guix Documentation Meetup

[Katherine Cox-Buday]

Blake Shaw <blake@nonconstructivism.com> writes:

> I'd love to know where you found trouble so that I can take that into
> consideration when developing a design strategy for the makeover.

When reading this, please keep in mind that I have a lot of gratitude for the 
various maintainers of this software and its respective documentation. 
Communication is very difficult, and relaying my experience and opinions is 
meant to convey that experience, and not to criticize anyone's efforts.

I think my frustration stems from the confluence of me not being familiar with 
scheme, how Guix writes scheme, how scheme the language and ecosystem work, the 
tools we have available to us, and then finally the documentation.

Not being a schemer (yet?), I can't speak with much authority, aside from the 
fact that I've written code in many languages, and most of these pain points 
are well addressed in others.

Usually, my frustrated workflow goes like this (warning: ignorance on display! 
:p):

- Identify something in Guix I want to do

- Open (or create) a file

- Start geiser

- Start writing Guile

- Come upon a semantic structure I want to write, and realize I don't know the
  Guile way to do it.
  
- In geiser, run =,a thing-i-want-to-look-for= (this is supposedly an apropos
  command that is supposed to search symbols for you). The command returns
  nothing. I realize I have to import the module implementing the thing I'm
  looking for first, thus defeating the purpose.

- Before, I would then go here[1] and try and textually search for the symbol.
  I have recently discovered the emacs function: =helm-info-guile= which makes
  searching a bit faster.

- Find that there are multiple, competing, modules which do the same thing in
  different ways.

- Realize I don't know which one to use, or which one Guix would prefer.

- Sometimes, realize that Guix has their own wrapper around one of the
  modules, and learn that something I thought was standard scheme is actually
  a Guix neologism.

- Import one and try it. Maybe import another and try it. Lose track of why
  I've imported things as I'm trying them because the module names have no
  indication of what they implement.

- Wish that Guix had a standard to prefix function calls with their module, as
  we do with =license:=.

- Have no way of automatically and programatically cleaning up imports to work
  around this.

- Forget what I was even trying to accomplish. Go to bed and try again
  tomorrow!

Specific to Guile documentation, I guess if I boil the above down, it would be 
something like:

Early in the documentation, directly address the intrinsic fragmentation of the 
scheme ecosystem, and how a new Guiler is meant to navigate that. Do so in 
terms that don't rely on experience with the Scheme ecosystem.

The Guile reference manual has this[2] section which, to me, is a paragraph 
which touches on this, and then much later has a blurb[3] on what SRFI is. I 
had no idea what =ice-9= was, and the first mention[5] of it in the manual is 
one of its modules. To my knowledge, what =ice-9= is, or why it's called that, 
is never addressed. It appears[5] I am not the first to be confused by this.

As a newcomer to Guile, and to scheme, I would expect Guile to give me its 
opinion of how to do things (i.e. which modules to prefer, what is considered 
"standard" in most schemes) until I've written enough Guile to form my own. As 
it's written, my impression is that the documentation relies on the reader 
knowing a lot about scheme coming in.

I feel there just needs to be an easier gradient for people trying to use Guile 
as their first scheme. It is not specifically Guile's problem, but as a service 
to its developers, the meta-topic should be addressed so a new developer is not 
left confused.

When we put a lot of work into something, it's really easy to fall in love with 
the idiosyncrasies of the thing, and to lose sight of what it's like to come 
into an ecosystem with no context. This can result in addressing things that 
feel important to us, the expert, but are really much further up the ladder of 
complexity.

When writing a landing page for a language, I feel the following is important:

*Don't overwhelm your newcomers.*
Your landing page should have few links, and they should directly address 
high-level questions:

- What am I looking at?
- How is what I'm looking at organized?
- What should people like me (e.g. non-programmers, programmers, schemers,
  people who don't speak English) be reading?
- A link to a site which provides easy to use symbol lookup.

The documentation can fan out in complexity from there, but the landing page 
must not be overwhelming.

Anyway, those are my opinions :)

[1] - https://www.gnu.org/software/guile/manual/guile.html
[2] - https://www.gnu.org/software/guile/manual/guile.html#Guile-Scheme
[3] - https://www.gnu.org/software/guile/manual/guile.html#SRFI-Support
[4] - https://www.gnu.org/software/guile/manual/guile.html#ice_002d9-optargs
[5] - https://lists.gnu.org/archive/html/guile-devel/2010-07/msg00045.html

-- 
Katherine