Comment by techdragon | Hacker News Reader

Comment by techdragon | Hacker News Reader

Parent Full thread

TLDR: Red desperately needs its own community maintained learning materials.

It’s all about signalling.

I’ve meant to learn more about Red for years but keep putting it on the back burner because I can never seem to find a cohesive set of material to self-learn from. (I want a book. Like https://doc.rust-lang.org/book/ - doesn’t have to be great, but it’s my minimum bar for entry, one cohesive document to learn the language, syntax, grammar, keywords, whatever standard library exist, maybe even a tutorial or two along the way... Perl, TCL, Python, Rust, Ruby, Go, Prolog, all the good languages have a book like learning document with sections and chapters I can work through, usually they combine it with their standard library reference too.)

The Red community does look absent/dead/deeply in decline by the standard of other languages. Myself, and I’m sure many others, pass over and ignore it time and time again because without a more obvious set of signals that its worth our time, (I have extremely limited time for learning dead languages, they are not worthless, it’s a matter of priorities) we just move on to other things after we fail to see why it’s worth learning any more than “Red is a cool language descended from REBOL, but it seems kinda like no one uses it so it might not be worth the time to learn, because if it really was awesome surely it would be more popular and have books and stuff”

Interesting point, thanks. We do have community maintained learning materials [1] (+ wiki itself), official docs [2] and formal specification [3]; granted, even if put together they don't match the quality of a cohesive user guide.

[1]: https://github.com/red/red/wiki/%5BLINKS%5D-Learning-resourc...

[2]: https://doc.red-lang.org/

[3]: https://github.com/meijeru/red.specs-public

Thanks for the links, I gave them a look through and some of the most useful ones are buried under poorly named links in other places, when they really should be prominent links on the main website. The material is available and somewhat easier to find than the last time I looked into Red/REBOL but it’s definitely in need of improvement.

Especially https://static.red-lang.org/red-system-specs-light.html - It needs work but it’s a LOT closer to the kind of documentation I’m looking for when starting to learn a language. I found it looking at the third link which looks like an attempt to improve on of the other pages you linked to.

It clarifies much of the remaining confusion I had regarding comments I saw on the internet about how you can just use any REBOL docs to learn Red, by explaining the bootstrapping process, and it does so clearly in the first few paragraphs no less. It’s this kind of writing style where the complexity is gradually built up in layers of understanding is very valuable for some people while learning a new language.

But the under construction docs have some real shocking writing in them. The data types page is pretty bad. “Where most languages have 6-8 base datatypes, Red has almost 50. Many of these have unique, literal forms. “ then a few sentences later “To use Red effectively, you should become familiar with all the datatypes available.” This is definitely not the way to encourage a new user, imagine how a person who has only learned JavaScript or Python is going to feel about Red when they read that page. I would bet that many novice programmers leave that page with the impression that Red is nearly 10 times more complex than the languages they already know.

It’s worth considering the lessons learned by the Rust community while building their documentation. While not every programming language will have Steve Klabnik and Carol Nichols to write tremendous documentation... every programming language can learn at least a little bit from how they built it up the Rust docs and made keeping them up to date an important part of the community’s priorities.

Thank you for taking your time to do a review! The prescriptive tone ("you should") on datatypes page doesn't really match the intent of the reference documentation (i.e. to inform), I agree.

Even if 50 vs 6-8 contrast sounds off-putting and overly sensationalist, it doesn't mean that language is more complex than its mainstream cousins. For example:

  ping @techdragon from http://www.rebol.com/docs/shell.html thread via hacker-news@techdragon.io
  today at 20:23:17 UTC
  say: your HN account was created on 11-February-2013 and has 1455 karma points

Is a Red code (or rather data) containing 8 examples of unique datatypes (@reference, URL, e-mail, date and time, integer and flavors of symbols). One can even write a DSL that would understand it and send you a mail over SMTP or something.

I'd rather say "datatypes belong to 3-4 separate classes, each with a distinct yet simple semantics", and that "the set of their literal forms is diverse enough to count half a hundred exemplars; that makes the language simple, and the code written in it expressive". And then maybe build-up a motivation to study these classes ("to use Red effectively"), outline the studying path to take ("become familiar").

I don't follow Rust closely, is there any summary/takeaway of its history with documentation and community's lessons that I can read?

That does sound like a better way to explain that there are many types. Definitely worth opening a PR and making that change to the data types doc page.

As for the history of the rust documentation. One of the best people to talk to would be Steve Klabnik https://steveklabnik.com so I would recommend reaching out to him.

TBH, the whole datatypes section needs a revamp. Will put Steve's blog on my weekend reading list. Cheers!

Reply on news.ycombinator.com