Carrying over a conversation from the Discord channel about documentation…
First of all, just want to thank the ReScript team for all their hard work putting together an amazing project. I came to ReScript from TypeScript and I just love the language. It reminds me a bit of when I first learned Ruby in terms of the “funness” of using it, it just sparks joy. So thank you , I’m grateful.
I feel like the ReScript docs have a split personality. On the one hand, ReScript positions itself as a complete language rather than just an OCaml syntax. On the other hand, the docs appear to have been written with the intention of leaving out some of the more “complex” parts of that language, i.e. advanced/discouraged parts inherited from Reason or OCaml (such as phantom types, abstract types, until recently the pipe last operator). These two ideas are dissonant, in my opinion.
I’ve been working with ReScript for the past month and even as a newcomer, I’ve found myself regularly referring to the ReScript, Reason, OCaml, ReScript blog posts and old BuckleScript docs. Some things that I use in my code that aren’t covered in ReScript’s docs:
- Phantom types
- Abstract types
- Polymorphic variants
- Extensible variant types
- Various BuckleScript decorators (e.g.,
- Lightweight FFI attributes without bs. prefix
Anecdotally, I see newcomers on the Discord channel regularly ask about syntax and the response is “oh that’s not in the docs because _______.” I also see responses from knowledgable community members expressing surprise that someone would need to go beyond the ReScript documentation, also somewhere from a core dev in a GitHub issue for the rescript-compiler repo. There seems to be a disconnect between established community members and newcomers regarding what the docs need to cover.
As a newcomer, what I’d like to see is ReScript’s docs cover every feature that’s supported by the compiler, including all the parts from OCaml (e.g., extensible variant types) that aren’t documented in the Reason docs. I get the impression that the team is attempting to limit what newcomers are exposed to in the docs possibly because the team intends to remove language features and doesn’t want users to write code that depends on them (I remember reading a response from a core dev somewhere to a docs question stating that a certain language feature wasn’t documented because it wasn’t “supported”). Or, the intention is to create a “beginner-friendly” language for JS devs to not overwhelm them.
Regarding the first (possible) intention, I could understand that concern, but if that’s the concern then there are some serious mixed messages being sent out. When the Reason/ReScript split was announced, the team made it clear that ReScript would be backward compatbile with Reason syntax, and by extension I would expect standard OCaml syntax, for a long time. So I’m left wondering what it means that certain features supported by the compiler might not be supported by the dev team (sorry, I wish that I could find the quote).
Regarding the second intention, I personally think that hiding complexity in the reference docs is counterproductive and sets the wrong tone. I’m not interested in learning a toy language, I want to have access to ReScript’s full power! Writing docs in a way that expresses that full power while also remaining user-friendly is a challenge, but that’s why technical writing is a critical skill. With the understanding that this is mostly a volunteer project, I see that the team has precious few resources to focus on documentation, but I would rather that the official docs err on the side of completeness. Honestly, I’m guessing that the typical profile of someone learning ReScript is a mid-level or senior dev who may have multiple languages under their belt and some rudimentary familiarity with functional languages. You should assume that we know what we’re doing rather than assume that we’ll feel overwhelmed when we see how much the language can do.
In an ideal world, I’d like to see three separate sets of docs: a “guide” that looks like the current ReScript docs, a “manual” that’s a comprehensive/exhaustive explanation of the language that includes every feature supported by the compiler, and an “API” docs section similar to what’s currently in place but more fleshed out. I understand that this takes time that the team may not have, which is why I’d like to contribute.
More importantly, though, writing good docs requires intention and clear knowledge of the team’s vision for the language. Because right now, as a newcomer looking at the docs, it’s unclear what the team wants ReScript to be. Is it its own language or is it an OCaml syntax? (Yes, I know it’s both, but you understand what I mean.)