3 ms·
Every new language suffers the same problem in its docs. The docs will show you: * Hello world (yay, printing to console, wow!) * How to declare functions (i
by kzhahou 11y ago
Every new language suffers the same problem in its docs. The docs will show you:
* Hello world (yay, printing to console, wow!)
* How to declare functions (impressive.... most impressive </s>)
* Their type system (cool, you have ints, bools, floats... I'm drooling over here!)
Please folks, for your language's own good, please put the unique distinguishing features FIRST in your docs. I don't care what your printf looks like! Just show me the 3 things I can do in your lang that I can't do anywhere else, and then you might actually hook me into trying it out.
- tomp 11y agoCouldn't agree more. Even worse are GitHub READMEs that usually go on and on about how to download, compile, install and run the compiler (how about making it so simple you could do it in 2 lines?!) and how to contribute code, without actually explaining what makes the language different.
- AndrewUnmuted 11y agoI would argue that, for many users, manually installing software leads to a greater understanding of that software. Take Linux/Bash as an example. What better way to learn Linux than to agonize over a Linux From Scratch installation, building CUPS, and successfully printing a test page to your printer?
- kzhahou 11y agoYeah but you already WANT to install Linux. This here language is fighting for my attention. It's not gonna win it by showing me Hello World.
- ori_b 11y agoI agree, and I've been thinking of replacing what I have with a better sample program. The problem is finding a small example. I mean, sure, I could post the code for my memory allocator, which showcases lower level raw memory manipulation, or a the formatting code, which showcases runtime type information, or some of the traits for iterables, but all of these take some time to digest, especially without first reading an introduction to the language. What kind of example would you like?
- jrapdx3 11y agoActually the "Hello ..." program is not so bad to show first. After all, it is a tradition, and like other introductions in the social universe, greetings serve a purpose. "Hello world" instantly tells me, ah, "this language is a lot like C with some interesting differences". From there quickly getting into the features that make the language unique will prevent reader boredom. Overall your site was nicely done. One aspect I particularly liked is that you described all of the syntax in the examples. I really dislike when a new language is presented without making clear what symbols mean, as if I would just automatically know. It will be interesting to see how Myrddin comes along.
- tomp 11y agoI don't see how installing a compiler would improve your understanding of the language the compiler is for. If anything, it would improve your understanding of whatever installing software (bash, makefiles, etc.).
- deleted 11y ago[deleted]
- andrewchambers 11y agoI think the Main features could be shifted above status. But I would like to point out the first example shows type inference, arrays/slices that know their own size, and tuples, all of which are very interesting in a language that is otherwise the same as C. Perhaps it can be made more obvious though.