The choreography stuff is actually really cool! Definitely agree this should be 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
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.
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.
You should put these up front also.
This is not an LLM talking but a kid who is learning to write with them, if you look closely. Still concerning