Skip to content
This repository has been archived by the owner on Oct 29, 2024. It is now read-only.

Documentation ideas #145

Open
fhammerschmidt opened this issue Mar 16, 2020 · 2 comments
Open

Documentation ideas #145

fhammerschmidt opened this issue Mar 16, 2020 · 2 comments
Labels
docs Technical writing feedback General feedback on what's missing in the Reason platform documentation

Comments

@fhammerschmidt
Copy link
Member

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
Copy link
Member Author

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

@ryyppy ryyppy added docs Technical writing feedback General feedback on what's missing in the Reason platform documentation labels Mar 16, 2020
@ryyppy ryyppy pinned this issue Mar 18, 2020
@jdeisenberg
Copy link
Contributor

Add a section about books / learning resources

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
docs Technical writing feedback General feedback on what's missing in the Reason platform documentation
Projects
None yet
Development

No branches or pull requests

3 participants