Re: Guix Documentation Meetup

[Katherine Cox-Buday <cox.katherine.e@gmail.com>]

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