Re: Guix Documentation Meetup

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

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