We’re prototyping a new Mojo language reference and would love your feedback as we refine it. The goal is to build a reference developers can trust.
This section is specifically about language reference, not tutorials or guides. Each page follows a simple rhythm with explanations, lots of examples where we can fit them in, as well as caution/pain points. That structure lets readers stop early if they got their answer, or keep going if they want the mechanics.
Another design constraint: reference material has to stay correct as the language evolves.
The direction we’re exploring balances human writing and editing with automatically generated reference so the pages stay maintainable as Mojo changes.
Since we can’t share a live preview yet, attached are screenshots of the prototype layouts. Some screenshots are from early mdBook prototypes. Others show the current design running on our docs site.
We’d especially appreciate feedback on:
Is this easy to scan?
Does the structure make sense?
Is anything missing that you expect from a language reference?
Anything here that would slow you down while coding?
If you regularly rely on references like cppreference, Rust docs, or Python docs, we’d especially like your take.
This is early design work. Your feedback will help shape how the Mojo reference evolves.
I use cppreference on a weekly basis, if not more often. I think it’s the best language reference that exists for any language, not just C++. In my view, this is because it’s extremely consistent not only in its prose style and text formatting but also in its high-level structure (e.g., section ordering) and visual cues:
Every page flows down from a concise summary, to technical details, to code examples, and then finally with references and links. This section order is the same for almost every page
Every piece of technical jargon (“C++ standard-ese”) is color-coded and hyperlinked to a dedicated page that has a complete explanation.
There are extremely visible visual cues to indicate language changes with new standards. (This is typically my primary use case for consulting cppreference.) Lots of these are visible on this page for constexpr, for instance: constexpr specifier (since C++11) - cppreference.com.
I like it. The first screenshot is a bit bare (the one with keyword references), but that’s a nitpick.
One thing popped into my mind while I was looking at the examples. It is nice to have simple examples, but it is also great to see more complex examples in the wild. Would it be possible to automate standard library scanning for examples and put them as external links to Github repo for people to explore? I think that might be very helpful for people who want to go deep on topic and concepts they are not familiar with. The sample links would need to be re generated on every major Mojo release, but this also makes sure that nothing got stale.
I think something closer to a BNF grammar (see JSON) might be helpful here. For example, I’m not told what I can put after except or assert, or what characters can go in string literals. What I can see of escape sequences is also missing raw unicode literals. Thinks like for loops also need their API contracts explained.
Mojo syntax highlighting should definitely be applied to this.
Ideally, we should make sure each block can be checked by the compiler, likely by piping it into the repl. Mojo already has a bit of a problem with out of date documentation and I think it’s important to avoid making that worse.
Nits:
For “String - Mutable UTF-8 Strings”, mentioning that most people should prefer codepoint indexing where possible is probably a good idea.
Assignment statements ignore var foo = ... and ref foo = ...
It should be available as an epub to read on small screens like smartphones, epub allow word wrapping while pdf are static both should be available options.
extension is gone.