> Perhaps the manual could be restructured to make this clear:

Another simpler and faster solution, which could be done without taking time
to the ocaml development team, would be to write some sort of
"Ocaml user manual's user manual": a small document indicating what parts of
the manual are important relative a given purpose, what are the more common
beginner mistakes to avoid, and a guide about the order in which the
different concepts should be studied.

Here is a list of the most common "autonomous Ocaml learner" mistakes I've
been faced to, as a former beginner and as an Ocaml evangelist with my
friends. We should discuss about that, then write it down in a user manual's
manual. Please note that these features are already dicussed in the manual:
my purpose is just to concentrate them in a place where they are focused on.

This would be my ---unsorted--- hot points list;
addition/modifications/removal are obviously welcomed:

- The compiler relies on upper|lowercaseness of the words
- Use currying for multiple-parameters functions instead of tuples
- Use of the fun keyword (it semmes to me the relevant part of the manual
has been rewritten between Ocaml 2.04 and 3.00, and the newer version is
much clearer).
- Don't reinvent hot water, and study at least the List library
- When two features have some common points, explain what's common and what
are their respective advantages (structures vs. cartesian products,
parentheses and begin..end, etc.). Beginners often can't imagine that two
different features have a lot of common parts, if it is not clearly set.
- Show how many different things can/should be done by pattern matching.
- usefulness of .mli files
- many other points I've forgotten.

I guess that those who have teached ocaml programming in an academic frame
will stress some very different points: this would be interesting to compare
with.
-------------------
Bug reports: http://caml.inria.fr/bin/caml-bugs  FAQ: http://caml.inria.fr/FAQ/
To unsubscribe, mail caml-list-request@inria.fr  Archives: http://caml.inria.fr