I love the ambition and the fact that this is not just another "state of the art in 2015" language like I see so often. It's trying to do something genuinely different. The field of "taking stuff out of academia and making it work" is a rich and underharvested one.
However, your light is hidden under a basket, to use an old metaphor. I'm having to go digging to find the genuinely new things going on. I suggest recalibrating the entire documentation with a focus on the new stuff. People on HN often complain about not having syntax examples front and center but I would say for you, the very first thing I you should be hitting your new visitors with is the choreography idea.
Set up a simple example of doing something like a concurrent remote counter that is atomically safe by the construction of your language and immediately dive in to what that means. Forget even educating us on the rest of the mundane syntax of the language, immediately dive in to what that is and what that means. I see in the docs/ dir that it probably hurts your programmer mind to cover the choreography before covering sections 1-8, but you can safely assume that if you intrigue with the choreography that they'll hang around to learn about the rest, whereas you can't safely assume that a new reader will wade through all the rest of the relatively mundane details to get to the really interesting stuff.
A modern language with a modern take on compiling a "program" that takes a unified view of the world at the programming language level, and then emits a "server" and a "client" (and perhaps other roles) as separate executables is a pretty nifty idea. Hit it early and hit it hard.
They did the right thing highlighting a working example front and center.
Nothing worse than PDFs full of theory and no working examples of the thing you’ll actually be doing all day.
I get that it’s important to show what abstractions and methodologies can arise out of using it, but with a good example that would be obvious. It’s the developer community using the language that will come up with the best abstractions (libraries) that - if it has an active community - helps shape what those novel developer experiences are.
A good analogy is the development of the skateboard - released first as a scooter - until someone knocked the handle off a started “surfing” down the street. Just show me the thing. I’ll tell you if it’s cool and how to use it
> What's the elevator pitch, one more time?" One ownership rule for memory, threads, and networks. No garbage collector, no complex borrow checker, and no network errors.
> not just another "state of the art in 2015" language like I see so often.
Newer is not always better. Lisp is full of good ideas that haven't stopped being good, even if a pure Lisp experience is understandably not to everyone's liking.
This is hands down some of the most constructive feedback we’ve received. You hit the nail on the head.
We definitely fell into the author’s trap of structuring docs "bottom-up" (Prerequisites -> Basic Syntax -> Advanced Concepts) rather than leading with our actual core innovation: choreography.
We are restructuring the main README/docs front page right now to lead immediately with a concrete example of choreographic execution (e.g., atomic multi-node orchestration / client-server emitting) before getting into standard syntax.
Really appreciate you taking the time to dig into the docs/ dir to pull this out it’s a huge help for our presentation.
Yes, but the OP is not the creator, which he claims to be. You can see the discussion about it on the discord server of Wyzer. This guy made all of this post, then left the account credentials to the real creator a few hours ago.
Yes, strong agree, normalcy resumes at some point. But you want the hook in first.
I mean, I'm phrasing that in marketing terms, but in this case it's in harmony with what your users want anyhow. We want to know ASAP why we should care about this language. So it works for everyone. Of course when it comes time to deliver the promise, normal programming language documentation is the way it is for a reason.
However, your light is hidden under a basket, to use an old metaphor. I'm having to go digging to find the genuinely new things going on. I suggest recalibrating the entire documentation with a focus on the new stuff. People on HN often complain about not having syntax examples front and center but I would say for you, the very first thing I you should be hitting your new visitors with is the choreography idea.
Set up a simple example of doing something like a concurrent remote counter that is atomically safe by the construction of your language and immediately dive in to what that means. Forget even educating us on the rest of the mundane syntax of the language, immediately dive in to what that is and what that means. I see in the docs/ dir that it probably hurts your programmer mind to cover the choreography before covering sections 1-8, but you can safely assume that if you intrigue with the choreography that they'll hang around to learn about the rest, whereas you can't safely assume that a new reader will wade through all the rest of the relatively mundane details to get to the really interesting stuff.
A modern language with a modern take on compiling a "program" that takes a unified view of the world at the programming language level, and then emits a "server" and a "client" (and perhaps other roles) as separate executables is a pretty nifty idea. Hit it early and hit it hard.