Documentation ideas

[fhammerschmidt]

This issue is an umbrella issue for all documentation pain points some of us went through when learning ReasonML. Feel free to drop a comment of what you feel is missing on the old documentation sites (reasonml.github.io, bucklescript.github.io, reason-react, etc.) to make reasonml.org an even better and more complete learning experience.

[fhammerschmidt]

I start with some points mentioned by @austindd in the Discord #docs channel:

• The use of polymorphic variants in general, but in particular, the concept of lower/upper bounds on the type, and how they are applied to type parameters for subtyping. This is certainly advanced, but it's not any more advanced than, say, implementing a custom class-decorator in TypeScript. It should be documented IMO.

• The syntax for module packing/unpacking. First class modules are not that hard for a JS developer to learn, IMO. It feels a lot like passing around classes in JS. Classes are just constructor functions, so they can be passed around and instantiated dynamically at runtime. The analogy is not perfect, but it's far from a foreign concept. It was one of the first "complex" things I tried to do when I learned Reason. Again, the biggest hurdle was not the concept, but finding ANY reference to the proper syntax in Reason. I had to read Real World OCaml, and then convert the examples to Reason syntax to get a feel for it. IMO, that's probably a bigger barrier to entry than introducing it in the docs.

• Functors. I feel the same way about functors as I do about FCM. It's not that hard of a concept at first glance. It feels a lot like a class constructor function from the OOP world, but with some very crucial differences. Most people will get the basic concept, and successfully create a functor. But then if they try to take it to the logical conclusion, they will run into issues. I'd rather focus on helping them solve those issues, tbh...

[jdeisenberg]

Add a section about books / learning resources