A few days ago, someone posted in Hacker News a language implemented in Racket. The docs of that langueage are quite complete and explain all the details.
But when I see a post of a new language I want to see how it feels. I want to look at a few well known examples like "Hello World!" or "Fibonacci", perhaps "99 bottles of beer", I'm not sure which are the mandatory examples. And then a few examples that show the strong and/or unusual part of the language.
Can we add a recomendation to add a section with examples to the docs of every language? How should it be called? Which examples? How many? (5? 10?)
3 Likes
I think Racket documentation overall really needs more examples. For example, the 6 Formlets: Functional Form Abstraction documentation is all well and good until I get down to section 6.4 or 6.5, and then I don't know how to put any of this stuff together. Often I found myself looking on grep.app or GitHub code search to try to find complete examples.
In theory it would be pretty easy for me to add more examples to the docs. If I figure out how a weird function is supposed to be used, I can click the [i] in the docs to go to the source code, then paste my new example into GitHub's web editor.
I haven't done this yet but I should start doing it in the future.
1 Like