reasonml.github.io icon indicating copy to clipboard operation
reasonml.github.io copied to clipboard

Modules page edits

Open asolove opened this issue 8 years ago • 0 comments

Before actually writing copy, I'd like to get feedback on a few suggested changes to the modules page in the language basics section.

Here's my proposal:

  • Add an introduction that defines modules by what they do and makes clear that they don't just group related code, but also serve as the means of abstraction and generic programming. (This occurs later on in the current article, but perhaps beyond where most people would read.)
  • Reorganize the example sections so that they are not grouped by language feature ("Module signatures", "Module functions") but instead by the purpose they serve ("Building abstractions", "Generic programming"). Add a callout to features from other languages that modules serve in Reason (templates, generics, type classes, etc.).
  • Similarly, rename syntax-related sections from the language names ("opening a module") to the purpose they serve ("Using code from another module").
  • Add more detail to the drawbacks section, which currently seems like a let-down after the rest of the article got you excited about modules. I'd like to add some more text on cases where modules aren't the right answer, and make clear that there are many cases where they are.

asolove avatar Jul 17 '17 16:07 asolove