Oh wow, I didn’t know there was a repo for the book, I totally should have looked!
Right, so I completely agree that the layout of the book could be improved and offer a better navigation experience for users of different skill levels. I took a peek at Rust’s “Learn Rust” page and I think it’s a wonderful format for guiding users, with maybe room for a slight improvement.
The page is a huge text “Learn Rust”, with three sections for different learning material. First the language manual, obviously a sensible choice. Then, the Rustlings course, which seems to be something similar to like Ruby Koans, if yall remember that. Then, there’s the Rust By Example book, which is a separate manual that dwells on semantics and structure of applications rather than the nitty gritty syntax and control flow stuff that so many manuals are filled with.
Later down the page, which you’re naturally inclined to see because the content cleverly starts halfway down the page load from the beginning, there are links to the Std api, and the dozen or so other book that have been compiled from various sub-sections of the ecosystem.
Granted, rust is a big overcomplicated, difficult-to-learn language, and is funded by a very large corporation, so it’s not like Crystal docs are gonna have 10+ books written about them in the near future. Still, there are things to be learned about how that page flows, and I think in particular that UX experience is lacking on the crystal-lang.org/docs page.
As far as arriving on a discussion format, I’m not exactly sure? I think there ought to be a subforum here on discourse for reasoned conversation about documentation in particular, and maybe there should be like a poll or something. The crystal-book repo may also be a decent place to have discussions, if there’s an easy way to facilitate that sort of thing.
I’m very curious about the way people use the documentation:
- Do they know ruby and just need type signatures and compiler recipes?
- As an aside, I wish there was a way to search specifically for the return types of methods. I don’t wish it so strongly that I’d like to write my own search tool for it, just that it might magically appear.
- Are they skilled programmers, or beginners?
- Are they looking for examples, method names, what format of help were they hoping to find?
I’ll be searching through the forum and trying to find out what experiences beginners are having with the documentation that exists today, and maybe get an idea for the “average” user.
Aside from all this, I’m an advocate of there being a Crystal By Example resource somewhere, and I’d LOVE to be a part of that.