Let me start by saying that I know that it is really hard to write documentation for less experienced persons, and that I myself am bad at that (ever after writing documentation for 20 years and actually teaching in schools for 3 years) - as you see, my sentences tend to meander on forever, without reaching a real conclusion. So please don’t take that as an , I do know, that the tutorials I would write wouldn’t be any better, they would be worse in other ways and I seriously appreciate your time spend writing them. That’s why I think they should be as good as possible, so that your time hasn’t been wasted.
The most important thing to always remember: it doesn’t matter, what you write, most people will never (no, really, never, ever) read that but just copy everything that is in code boxes. So the upmost importance is that they are as self explanatory as possible, at least in the order they are presented (nobody can expect to skip 10 examples and understand the 11th one).
First of, this reads like an academic paper, which is the cliche of functional programming - not being usable “in the real world”. If it where Haskell, you could play with that cliche by mentioning monads and endofunctors, but this is OCaml, so either no “fancy words” or in a humorous way to differentiate the language. When trying to write for “non functional programmers” avoid sounding like an academic paper or a C or C++ standard at all costs. This does not mean avoiding the proper terms, but always define them with a concrete example and never ever more than one at a time. As soon as an example needs two “new words”, it is the wrong example at this time (see later).
As it is now, the whole page is a tutorial for functional programmers, not non-functional programmers.
But now to the actual phrase: what you have written, is an elaborate paragraph telling me I’m going to learn “the basics”. Which is nice, but expected, it is the first page of a tutorial for beginners, after all. And for people who don’t understand the used terms - closure, that is something about programming in a hammock, right? - they are not that “interesting sounding” that they would be motivated. How many people have ever approached you, demanding that you teach them “the ability to write expressions, name values or leave them anonymous, appropriately scope names, handle multiple definitions of the same name, create and use closures, and produce or avoid side effects”? If you declare a goal, either make that sound (at least) somewhat interesting and sexy, or use a “known” term (the number of which hopefully grown throughout the tutorial), or don’t write that at all - again, the goal of a tutorial is obviously to teach things.
Then the next paragraph (brace yourself!).
In OCaml, functions are values.
Don’t get me wrong, this is a great and important thing to say, and most people will understand that, if the next phrase is something like “So you can use functions as arguments to functions and return them from functions, for example”. But
In comparison to other mainstream languages, this creates a richer picture between expressions, values, and names. The approach in this tutorial is to acquire the related capabilities and understanding by interacting with OCaml in UTop. This hands-on experience is intended to build understanding by experimentation rather than starting with the definition of the concepts.
I don’t know how to write about this without needlessly offending you, but this is “some slimy kind of insurance salesperson marketing speech” kind of cringeworthy. Don’t do that, except if trying to be funny. This is something Oracle, SAP or IBM (actually, it’s more like Accenture, McKinsey and their ilk) would have written and we don’t want to program in COBOL, do we?
First: don’t do that on the first page. You are way too fast.
The problem is that you are showing a declaration which uses 6 new concepts in the first line, of which 4 are special and/or ugly OCaml/ML syntax. And the main problem to learning functional programming is understanding recursion and recursive data structures, the 6th.
type 'a tree = Node of 'a * 'a tree list;;
type
, which declares a type. So far, so normal and understandable
But now:
'a
for a type variable. The concept of a type variable already confuses people, having that strange '
makes it worse and the backward syntax doesn’t help either. And then there is Rust which uses that for lifetimes.
- the
of
: is that a keyword, another strange type of metavariable, a special type?
- the second worst of all of ML syntax, using
*
in the type of a tuple (whoever came up with that: you don’t use +
for sum types, do you?)
- the worst of the syntax, the “backwardness” of type definitions
'a tree
instead of tree 'a
and tree list
instead of list tree
And last: this a a recursive data structure, a tree. Most programmers have never used a tree in their whole life, much less the concise, recursive form. They have more practical knowledge of monads than of trees or recursive data structures or recursion in general.
Then afterwards the mentioning of alpha
. By mentioning only the correct “pronounciation” of 'a
you make it seem as if the only part of the whole expression worth talking about is the fact that 'a
is actually an alpha. By that, you make it (subconsciously or consciously) clear to the reader that you expect them to understand the whole gibberish in the box and they give up.