[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Guix Documentation Meetup
From: |
Katherine Cox-Buday |
Subject: |
Re: Guix Documentation Meetup |
Date: |
Tue, 14 Dec 2021 10:01:34 -0600 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) |
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
Re: Guix Documentation Meetup, zimoun, 2021/12/13
Guile documentation, Ludovic Courtès, 2021/12/20
Re: Guix Documentation Meetup, adriano, 2021/12/21
Re: Guix Documentation Meetup, Blake Shaw, 2021/12/10
Re: Guix Documentation Meetup, Blake Shaw, 2021/12/13