Discussion: How should we document the language itself

[phated]

Currently, not much of the language itself is documented on the website. I just found Bindings today and noticed that it has a pretty plain way of representing the language constructs for let bindings.

I wonder if there's a better and more clear way for us to document the actual language.

[ospencer]

I originally envisioned that section to just include the formal syntax for the construct, along with any additional information users should know about it, and maybe an example or two. I actually really like how Python does its language docs, and I think we should largely follow suit: https://docs.python.org/3/reference/lexical_analysis.html#identifiers

I made a lot of those pages a long time ago without much thought... I think this would be a good way to condense them and have useful info!