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.
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.