Re: Guix Documentation Meetup

[Katherine Cox-Buday]

Here is some analysis on various popular languages' documentation landing 
pages. I did this on Sunday, but I held it back from my previous message 
because it was already quite long, and I was worried this would be seen as 
over-critical and maybe raise the ire of various language fans.

But I think it might add to the conversation and help create better Guile 
documentation, so I'll risk it :)

For context, the only language on this list I really know well is Go.

Guile:
======
- Tutorial for extending a C program with Guile
- The manual
- Scheme Resources
  - "The Revised^6 Report on the Algorithmic Language Scheme"
  - "" but 7
  - "" but 5
  - (more links that IMO are only meaningful if you already know Scheme)

Overall, I'm left feeling like I have a clear sense of direction because it's 
apparent to me that I should click through to the reference manual. Experience 
with the GNU ecosystem helps here. I am left wondering whether I should click 
on any of the other links, and what I might be missing by not doing so. But 
clicking through reveals lengthy documents that I don't know if I should read 
yet or not.

Once I do click through to the manual, I am in a pretty familiar GNU document, 
and the other comments about this document become applicable.

The one thing I would add here is that other languages have a separate 
symbol/library explorer with a few more bells and whistles to support jumping 
around. It would be nice if Guile not only curated opinions on which modules to 
use, but used a separate, more featureful site for that.

Go (https://go.dev/doc/):
=========================
- A blurb trying to sell Go
- A link on how to install Go
- Links to tutorials and opinions on how to write Go.
- Links for very specific topics like editor plugins and fuzzing.

Overall, this seems cluttered and disorganized. For some reason there are 
several links to tutorials on very specific topics before there is a link to 
look at the packages in the standard library. These tutorials seem to be 
interspersed with more fundamental, important, beginner topics, and I'm not 
sure why.

The link to look at the documentation for the standard library -- something a 
developer will be working with a lot -- is titled "Package Documentation", too 
generic a term.

Once I do click through, there is a great site for navigating the standard 
library which explains what packages are for, and provides various navigation 
elements for jumping around.

Rust (https://www.rust-lang.org/learn):
=======================================
- A link to a book
- A link to a course
- A link to rust by example
(note the support for 3 different kinds of learning styles)
- Core documentation
  - The standard library (here is, by way of being the standard library, an
    opinion I can borrow for how things are done).
  - (more links I skipped because I don't know rust, and I"d start with the
    above)

Overall, I am left feeling like I know where I would start depending on how I 
want to learn, and have a quick reference to the standard library's API.

Once I click through to the standard library, it suggests to me how to read it, 
and addresses the meta-question of what I'm looking at. I haven't used this 
site, but clicking around, it appears to have decent navigation elements for 
jumping around.

Python (https://www.python.org/doc/):
=====================================
- A blurb on how the different ways to consume the documentation.
- Links grouped by self-reported expertise with the language

If I click on Beginner's guide:

- Link to explanation of what Python is
- Blurb on how to get Python
- Links for non-programmers to learn
- Links for programmers to learn
  - Acknowledgment that I've been reading wiki pages. I now have an
    explanation for why what I've been reading feels cobbled together.
  - A link to a separate beginner's guide overview with more general
    information about the language.
  - A long list of books, websites, and tutorials (note there is no opinion
    given on which I should begin with)

Overall, I am left feeling overwhelmed, and like I must independently find a 
curated tutorial which will give me opinions I can use until I can form my own.

But wait! Had I clicked on "Python Docs" instead of "Beginner's Guide", I get 
something much easier to consume:

- A Tutorial which simply states "start here". As a newbie, OK!
  - This looks like a book
- Library reference
- Language reference
- General links to support usage

This is not overwhelming, and I feel like I have a small enough set of options 
to click through that I can find what I need. Further, it looks like a curated 
opinion of how I should do things, and in what order.

-- 
Katherine