ocaml.org icon indicating copy to clipboard operation
ocaml.org copied to clipboard

Include misc feedback from @Release-Candidate

Open cuihtlauac opened this issue 1 year ago • 3 comments

This is follow-up to thus discuss thread:

  • [x] Rewrite line 15 w/o corporate gibberish style
  • [x] Make sure terminology is always introduced after the examples
  • [ ] Make sure no example introduces more that exactly one concept
  • [x] Mention Environment is named Context in some other languages

cuihtlauac avatar Nov 13 '23 14:11 cuihtlauac

From the Discuss thread:

>> Here, the learning goal is “pattern matching between let and = is available for user-defines variants”. Do you have a better example in mind?

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;;`

How can we revise the 'a tree example with a simpler example? Should we just introduce 'a / type variables here with a simpler example and forget about pattern matching this early in the tutorial?

Perhaps the same/similar example as in Tour of OCaml?

# #show option;;
type 'a option = None | Some of 'a

# let f opt = match opt with
    | None -> None
    | Some None -> None
    | Some (Some x) -> Some x;;
val f : 'a option option-> 'a option = <fun>

christinerose avatar Nov 30 '23 09:11 christinerose

I've done some work on Values & Functions to address these suggestions, but I'm not able to do the "Make sure no example introduces more that exactly one concept" without help.

christinerose avatar Nov 30 '23 10:11 christinerose