As you can see, there’s still work to be done. For example, we’re going to make the “Download” and the “Standard Library” boxes a bit smaller. And, clearly, this design is using placeholder content.
All the design has been done with one thing in mind: Flexibility to arrange content in such a way that we can show different groups of users what they need to see. We can rearrange and experiment with the blocks you see on the page.
There is a progression from beginner content to advanced content, focused clearly on the things that people need to learn to be productive with the language.
Now… here’s what I ask you to do: Imagine which documentation do we have to give people here on the main page of the Learn Area to make them happy and productive with OCaml:
Which topics would have to be covered by the “tutorial blocks”?
Which books do we feature?
The point of the main page of the Learn area is to quickly guide people into the direction they may be interested in.
Your feedback directly helps us prioritize the creation of missing documentation and helps us rearrange & improve the existing documentation. Please do be specific and give us titles for the pages you want to see, as well as a short description about what the user would find there.
I have a small request more on the technical side, whenever we use cards to layout content it would be good to make the entire card clickable as the hyperlink target, this way users don’t have to jump through hoops to position their mouse cursor. Also makes it easier to tap on mobile devices.
This is looking great! I think the book covers in particular make the page more inviting.
Regarding the “tutorial blocks”, here’s what I think we should have front and center:
Installation (maybe obviously), including the difference between system-wide install, and opam switches.
Language tour (the bottom part of the current “Your First Day with OCaml” page)
Development best practices (Including everything starting from the “First Steps with OCaml” heading on the “Get Up and Running with Ocaml” page, plus the first four or five items from the “OCaml Best Practices” page)
In my own experience, installation and language overview were not an issue, but the third heading was challenging, and I wanted to see all that information in one place. Specifically:
Dune vs opam
Installing and updating dependencies
Opam’s DWIM VC repository behavior (useful but surprising!)
The very basics of Dune’s configuration files for libraries vs executables
Source code formatting and running tests
Working with shared code repositories
This last one is important, particularly because of Opam’s VC-aware behavior. I or someone else has added a new dependency in a different checkout of the repository. They have committed the result (what is the result? a lock file?) and pushed it. I pull those changes into my clone. Now what?
I think it’s important to have that information near the top of the list of newbie resources; something they’re going to get to on day one.
I like your idea of grouping all information related to how to deal with dependencies, dune/opam, ocamlformat.
I could see this information being part of the “Platform tools” tab, with a tutorial block that shows the most relevant tutorials on the main Learn Area page.
This looks great! I like the new design more than the previous one
In my experience, people who only start learning a new language, are interested in two things:
How to install all the tools (IDE, plugins, compiler, etc.)?
What learning resource to choose (book, course, exercises, etc.)?
I believe it makes sense to optimise the learning page for absolute beginners as they are the main target audience. That’s why I think that the “Standard library” and “Calling C libraries” links might not necessarily be useful in the beginning as this is something people don’t usually need when they start learning a new language.
If I could suggest a slightly different order of sections, I’d recommend:
Download.
Recommended videos.
Recommended books
I see “View all 22 books” link in this section. But a new person to the language will never look at those 22 books and try to decide which one to choose. They’ll probably choose the first one in the list. I understand the sentiment behind being fair but humans are lazy and they want to make decisions quickly. My recommendation would be to put only free books in this section.
Also, I had a great time learning OCaml using Real World OCaml, and it’s also free. So I believe it should be highlighted as well.
Playground tutorials.
Exercises.
Step-by-step guidance.
Advanced interactive tutorials.
The idea is that more accessible resources for beginners should be closer to the beginning while more advances resources should be closer to the end.
Yes, that kind of input is also exactly what I’m looking for. Indeed, feel free to rearrange freely and imagine an ideal situation. I already asked for a smaller recommended video block as well, so that we can have this progression of content from beginner to advanced also in the video recommendations.
new person to the language will never look at those 22 books and try to decide which one to choose. They’ll probably choose the first one in the list.
Agreed, there’s a lot of value in eliminating unnecessary choice. We figured two books is a good number because if one book doesn’t work for one person, they could still try the other one.
So everyone, keep the feedback going: when a few more people have chimed in, I think I can see much more clearly where this is going!
I’ll also actually feel confident in that I am not overlooking something obvious between the myriads of possibilities. The difference between the first version of the install page at Install OCaml and what we ended up publishing is immense and it’s only thanks to you all!
Orange [core]: minimum set of must-know topics, ubiquitous or initial setup
Yellow [level 1]: central topics excluded from core, very frequently used
Pale Yellow [level 2]: optional topics, learn-on-need
Pale Green [level 3]: other topics
Regarding the position of the cards, only the colouring/onion layering/distance from the centre makes sense. Positions between elements are irrelevant.
Comments and suggestions are welcome. Write access is provided on demand (my mistake, I should have picked another tool).
I would make some things closer : opam publishing / using opam / opam switches / dune build / dune test / dune […] & packages / dune manual [all things which control the OCaml ecosystem but doesn’t directly deals with the OCaml languange] odoc could be close if dune stanza should be used.
flambda close to opam switch is fine.
merlin should be close to editor setup
memory model near FFI
using ppx should be closed to sexp, JSON and Yaml since I guess they are related
error handling near monad since monad is one way to handle errors.
1st class modules near modules & functors
Perhaps mdx near odoc… perhaps.
Effect near Eio (a 5.0 feature with concurrency aspects)
But this seems to be quite comprehensive… There will always be something missing (LablGtk ? an XML handler ?), but this whole picture covers a lot of things.
Most of what you describe should be in scope for the “dune build” card. We believe Dune needs to be split into several documents to be easier to digest. We tend to think external libs and testing should not be part of the bare minimum / basic principles, but we publish this precisely to trigger discussion.
We’ve been working on an overall outline for “an ideal state” of the Learn area. I took the current Work-in-progress, and updated the Miro board at Miro | Online Whiteboard for Visual Collaboration. For many of the topics, we now propose tentative titles of documents relating to them. Some topics are still in need of titles.
Here’s an image of the state at the time I’m making this post:
Hi everyone, I’m working on implementing the changes for the new Learn Area and I’m currently looking at the books area. It made me wonder… do you know of any excellent new books that are not yet on OCaml Books?
The Little MLer is a fantastic introduction to functional programming and, in particular, thinking recursively. It’s in SML but includes a page on translating the examples to OCaml.
I also can’t recommend highly enough The Functional Approach to Programming by Cousineau and Mauny, which uses Caml (no object system yet!). But it clarified many concepts that I hadn’t previously grokked. One of the huge advantages of OCaml is its stability and I think all of the examples still worked.
Maybe not so relevant for an OCaml books page but I also read the classic ML books when I was learning OCaml and they were a HUGE help: Paulson’s ML for the Working Programmer is phenomenal and I also recall Elements of ML Programming and Introduction to Programming using SML being helpful. SML and OCaml are close enough that both concepts and syntax readily transfer from the former to the latter.
The difference between the first version of the install page at 
