As a newcomer to ReasonML, I recently wrote a two-part tutorial (part one and part two) to showcase to other people how the language can be used to elegantly solve real-world problems. Feedback is welcome!
Having finished part one, it’s very well written. Just one point of confusion – I am reading this line:
Partition the original 6×4 container into the same number of rectangles as the number of children at level 1 (6 partitions)
But when I count the children at level 1 in your hand-drawn diagram: A, B, C, D, E, F, G, I get a total of seven. This had me confused for a moment, until I realized that partitions = rectangles - 1.
It should say 7 partitions. Thanks for spotting the mistake. I’ll fix it.
Part 2: Overall, it builds very nicely and keeps information in manageable compartments.
- After the text “This is called a let binding,…“, you might want to note that you have explicitly annotated/specified the data type
- Your description of data types is quite elegant.
- In file
tree-type-definition.png, the vertical bars look like slashes (probably an artifact of your syntax highlighter)
- “Note that in the visual output, only leaf nodes (terminal nodes) remain.” You might want to mention this in part one after you finish the first classic tree map.
y0, etc. are verified at compile time and become indices into an array at run time.
- “Below are two passing test cases from the test code"” The
- Excellent explanation of partial application.
- Thank you for giving the formula for calculating the aspect ratio rather than asking us to derive it ourselves
- Good explanation of the double set of parentheses for the tuple.
- “all nodes must already be in the result array, meaning we can return the result array” – do you want to say list instead of array here?
- In the discussion of the general case, do you want to explain what
One general comment: I am the only person in the world who doesn’t like dark-theme editors; I find the low contrast makes it hard to read the comments in the screenshots at smaller font sizes. I’d rather see non-syntax-highlighted text rather than an image of the code (or have the image link to the github source), but I realize that text would take up too much vertical space in the article, and links would be too difficult to add manually.
Thanks for phenomenal feedback. I have incorporated most of them into the article and added a credit to you at the end.
I added a note clarifying this point of possible confusion.
I added a footnote to quickly explain it.
I think List.rev might not be optimal from a pedagogical stand point so I changed the implementation and updated the tutorial accordingly.
I’m using screenshots instead of regular code blocks because I haven’t found a good syntax highlighter for Reason.