Rewrote set tutorial from scratch.

[NebuPookins]

Issue Description

Fixes https://github.com/ocaml/ocaml.org/issues/598

Changes Made

This version of the tutorial now demonstrates how to use Set with arbitrary types. It also provides a demonstration on how to reason about the behavior of functions based on their type signatures.

• Please check if the PR fulfills these requirements

• [x] PR is descriptively titled and links the original issue above
• [x] Before/after screenshots (if this is a layout change)
• [x] Details of which platforms the change was tested on (if this is a browser-specific change)
• [x] Context for what motivated the change (if this is a change to some content)

[NebuPookins]

Thanks for the feedback. I think I've addressed them in this latest commit.

[Octachron]

After a quick glance, there are good ideas in the rewritten text. Nevertheless, I see two issues. First, the text is lacking an introduction. Second, there are two tutorials fighting each other currently: a "how to use a functor" tutorial and a set tutorial. Currently, the Set tutorial is losing in term of contents. The two tutorials need to be split.

[NebuPookins]

Hi @Octachron

I've skimmed through your various suggestions and I will attempt to address them in another revision of the pull request, but I'd like to address your "overarching feedback" here:

There are two tutorials fighting each other currently: a "how to use a functor" tutorial and a set tutorial. Currently, the Set tutorial is losing in term of contents. The two tutorials need to be split.

This rewrite was done in response to https://github.com/ocaml/ocaml.org/issues/598 where someone pointed out that the original tutorial gave an example of creating a set of strings via Set.Make(String) and left it at that. They said that someone new to OCaml would probably then try something like Set.Make(int) which would fail and they would have no idea what when wrong.

I agree with their assessment, because as a new OCaml user, I was also surprised why one worked and the other didn't. This might be especially likely for people with a Java background or similar, where the type for String is called String (capital S) and the type for integers is called int (lowercase i).

After performing my own research on why Set.Make(String) worked but Set.Make(int) didn't, and then meditating on the best way to convey this to other new OCaml users, I think it is unavoidable to address the topic of types, modules, and functors.

This tutorial is primarily intended to be a tutorial on the using sets in OCaml with a target audience of people familiar with programming in general, but with zero OCaml experience (e.g. someone who has used set-like data structures in Java or other similar languages). I did not intend to focus specifically on how to use functors in the general case (to be honest, I don't know how to use functors in general in OCaml), but I do feel there is a minimum you need to know about functors in OCaml to actually use the Set module.

If there are more words spent on the topic of functors than on the topic of sets, it's probably because I expect most readers to know basically what a set is and how it works in other languages, but to be utterly confounded by this concept of "functor" which is likely to be totally alien to them. Especially since I don't expect the reader to have a good understanding of "modules" in the first place when they first stumble onto this page (I did not have a good understanding of modules when I first encountered this page).

Does that make sense?

Edit to add one more thought: One possibility is to tell the reader to first read the tutorials on modules and functors before reading this tutorial on sets, but I feel like that would be too discouraging to a new OCaml user. So I think it makes sense to do some minimal introduction to functors here, rather than ask the reader to learn about functors first.

[Octachron]

I agree that the tutorial should not assume too much familiarity with functors. And that it is necessary to have good functor tutorial. However, this is the set tutorial. The reader explicitly looked for explanations on sets in OCaml when they reached that page. You cannot decide in their stead that they are familiar with sets and just need to be told about functors. And your current explanation of functors is more on depth that the one in the functor tutorial. There is something amiss here. The set tutorial should focus on sets, maybe explain some details about to define set of custom types and link to the functor tutorial for further explanation. The detailed explanation on how to use a functor should go to the functor tutorial.

[NebuPookins]

The reader explicitly looked for explanations on sets in OCaml when they reached that page. You cannot decide in their stead that they are familiar with sets and just need to be told about functors. And your current explanation of functors is more on depth that the one in the functor tutorial. There is something amiss here. The set tutorial should focus on sets, maybe explain some details about to define set of custom types and link to the functor tutorial for further explanation. The detailed explanation on how to use a functor should go to the functor tutorial.

We might be at an impasse here. What's the conflict resolution strategy used for this repo if some people like the change and some people don't like it? Do we vote, or does "one dislike" veto the change, or what? I don't want to bother addressing the minor issues (e.g. the "function language" -> "functional language" typo) if the PR is likely to be rejected in the end.

In case it'll sway your vote, I claim that even if this tutorial isn't the ideal tutorial you have in mind, it better serves the goal of having a new OCaml programmer become comfortable with using Set than the previous tutorial, and so it'd be an overall positive if merged in. That's just my (probably biased) opinion, though.

[Octachron]

I am not sure why you think that we are at an impasse? What is the issue with rerouting the functor related explanations to the functor tutorial?

[pmetzger]

We could split this in two perhaps? Explain functors in one part, and the data structure itself in another, and advise readers to skip the functor section if and only if they're comfortable with functors?

[pmetzger]

(BTW, this is a very clear explanation of functors for the new user who thinks they're just interested in sets but needs to understand functors to make use of sets.)

[NebuPookins]

What is the issue with rerouting the functor related explanations to the functor tutorial?

I re-read the tutorial I wrote, and I actually don't think I spend very much time talking about functors at all. As far as I can see, this is the only explanation I give on functors:

Set is a functor, which means that it is a module that is parameterized by another module.

Every other sentence in the tutorial is about Set.

The word "functor" appears a total of 4 times in the tutorial, including the sentence I quoted above which gives a one sentence definition of the term. The other 3 uses are always "the Set functor", meaning I'm talking about Set, but I thought just saying "the Set" would sound too awkward: For example, I think "The Set provides a function Make which..." doesn't sound right; Set is acting as an adjective here, and I need some noun. So I used "functor" as the noun, but the sentences are about Set, not about functors.

I could change it to "module", as in "The Set module provides a function Make which..." but then I think this would cause extra confusion to a beginner because I had previous said Set is a functor, and now I'm saying it's a module. It's true that functors are modules, but I don't want to distract the beginner with that detail, which is why I avoid bringing that up until we get to the "Technical Details" section.

So I guess my issue is that it's not clear to me what in the tutorial seems to be "about functors" that should be split off.

[Octachron]

Hm, I think that I see what you mean. From my point of view, when you say

you could search through the documentation for the original Set functor to try and find what function or value you should use to do this, but this is an excellent opportunity to practice reading the type signatures and inferring the answer from them.

you are discarding the set data structure and talking about how to make sense of the result of a generic functor. Similarly, the sections Creating a set and Working with a set are not really about sets but how to construct a value from an abstract type. For instance, a section about creating a set should have created an empty set by the end of the first paragraph, but with the current focus on type-directed navigation of the signature, that only happens in the 7th paragraph. That makes sense for a module or functor tutorial, but that seems quite strange for a tutorial about sets.

Maybe another editing direction will be to start describing the basic set functions before diving in type exploration mode to discover more functions for creating or updating sets. I think that grounding a little more those sections in the data structure being described might remove my impression of reading a generic functor tutorial.

[NebuPookins]

I think I better understand your point of view now. Let me think about this some more and I'll probably submit another revision.