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.

Thank you for this comment. I had mostly shrugged off this project as “neat” but didn’t go digging until I read this.

The choreography stuff is actually really cool! Definitely agree this should be front and center

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

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.