@kopecs @cjr @octachron I appreciate you taking the time to provide feedback.
I see what you mean about the analogy, its well taken. When I first began using polymorphic variants and they began making sense, my mental model was thinking about “ordinary” variants as having a localized scope based on module-paths while polymorphic variants can be thought of as globally scoped, and the folder vs label analogy came to mind. I introduced the concept to some friends in this way before going over the notation with some examples and it seemed to point them in the right direction, but I was able to supply the caveats that it is a loose analogy, and we didn’t stick to it the analogy very long. With some distance from the text over the last few days and your concerns well stated, I agree that it lacks precision and isn’t well suited to a lesson. I removed it.
If you happen to have a better analogy, I’d be interested to hear it. Otherwise, the need for an analogy survived from the first draft and upon reflection I feel like it isn’t required anymore given the rest of the text.
@cjr Agreed, the analogy doesn’t map well under scrutiny
@kopecs I also agree with the abundance of bolding. I used it during editing to help me with pacing. I got used to it and didn’t think to take it out. Like you said, it is highly subjective and arbitrary. Removed.
@octachron By “evolving” I intended to capture the process of developing a state machine as smonat described here, or the process of incrementally defining functions as mentioned in the manual here, and I agree that my phrasing doesn’t express it well and got lost in edits. Incrementality would be a better term than evolving.
@octachron To your larger point about motivating the subject with concrete examples, I agree that those are vital, and I am currently working on a lesson that uses Garrigue’s paper as a starting point, with additional examples motivated by message board discussions. I am curious which would make for a better first lesson: the motivation (through common use-cases) or the notation/cs concepts (through more abstract \A's and `B`'s). It may be that the motivation lesson is better suited as the first lesson, or that they are merged into one. I’m not sure at this point.
For the other points, I’ll look into them further and make updates. I really appreciate the additional depth and clarity it brings.
Incidentally, lessons on polymorphic variants and GADTs share a “cart before the horse” problem, where the notation and cs concepts benefit a later discussion on motivation, but the same is true the other way around. Which is the cart, which is the horse? Its a subjective call, and I’m happy to figure out which way works for OCaml.org as these lessons are improved.
Thanks again for the feedback. I’ll reach out again for your thoughts once the 2nd lesson is ready.