Making OCaml Accessible and Learnable for More People

Community
1

OCaml is a wonderfully powerful language that has historically never hit critical adoption. Mainly because of it’s perceived perception and developer experiences when actively trying to learn. This is to many developers out there really upsetting. I am going to outline the experiences of many people I’ve worked with, spoken to, and my personal experience trying to learn OCaml.

When beginning the journey of learning OCaml, most people nowadays start off with Real World OCaml which is a dive into OCaml the language, and parts of the OCaml Ecosystem. I’ve had a chance to read the book from end to end 3 times. YES. 3 Times. It is very well written by some of the brightest in the community. Prior to this book there was no reliable source to learn about OCaml aside from the Manual. So I want to give praise to the authors for stepping up and representing for the OCaml community. However I do have a pickle with some of the book and I hope to explain it as best as I can. The code examples in the book are not simple enough. The book has code examples that go over pattern matching, variants, and polymorphic variants, etc. Often times when teaching these concepts that may be complex or new concepts to people it is best to explain them through examples or concepts that are already familiar to them, Instead of with Terminal Colors, RGB, GrayScale, Logging server types. Maybe break it down to things that people may encounter everyday. This will help people just concentrate on the new complex/unknown thing they are learning instead of the new thing and the concept used in the example that they have to think about and judge whether they understand the example. Just want to remind the OCaml community that you are extremely bright, talented, and highly educated scholars for the most part. Many new comers may not be like the majority in the community. So please make your examples more relatable, down to earth, understandable to someone that might be in middle school or high school with average intelligence. Aside from the code examples used to try to teach the concepts the book may want to add a little more line height in the code examples to provide clarity.

The OCaml documentation is very good. Especially if you are a computer. Seriously, please make OCaml’s documentation more digestible and understandable. Not just generated documentation that has a description and type signature. Provide examples usage and example code, and even more descriptions that don’t span 1 or 2 sentences. Take a second to describe the parameters. Normal people are not computers. Average people may not have access to higher education, average people have never read academic papers, or written them. Make documentation something that is digestible and understandable. Please I urge you. Add some colors, not just black and white. Make the documentation feel human. Please.

Secondly, if you write a library please document your code outside of computer generated documentation. Most libraries in the OCaml ecosystem are very closed despite being “open source” and provide no support, have cryptic commit messages, and make no attempt to involve the community or even foster one. I’ve seen this with several “open source” OCaml projects that come from companies like Jane Street among others. If you want people to use OCaml and use the awesome tools you guys make that make everyday developers feel like they have super powers, be open, be helpful, and actually join the community and help foster one by engaging with the community. As inspiration I hope the OCaml community would look at the Golang, Javascript, Ruby, for inspiration and as an example in their documentation and open source efforts that have made them giants in open source and adoption.

OCaml community as far as I can make out communicate through forums or freenode. It’s 2017. Please pick something that is somewhat approachable to hold discussion with new comers, the curious, and people who want to help people learn OCaml. Seriously, this is really frustrating. I look at all the other communities that have slacks, and gitters, even the new ReasonML has a Discord Channel the is thriving and even seasoned OCaml programmers use to talk, help, and inform.

If you know OCaml well and have time on your hands write guides, blog posts, tutorials as much as you can. Seriously if theres any community thats starving itself out of great developers who want to learn, it is OCaml. It is quite a phenomenon to be honest. This is the only community i’ve seen that keeps information tightly wrapped in closed circles and forums that and doesn’t make new findings circulate to the rest of the community. WRITE WRITE WRITE! Blogposts, guides, tutorials. This is critical. I’ve talked to many 77 people who tried to learn OCaml once, more than once, succeeded, and failed. These are topics they wish were better explained with documentation, guides, tutorials, blog posts:

  • OPAM

    • Publish a library
    • Install all Project Dependencies
    • Add new Project Dependency
    • Update Project Dependency

  • OCaml Extension Points (ppx)

    • How to write them
    • How to use them

  • Polymorphic Variants

    • What is this
    • When is it useful
    • How to use

  • Generalized Algebraic Data Types (GADT)

    • What is this
    • When is it useful
    • How to use

  • Testing

  • How to test in OCaml

  • Setup with Build Step

  • Build Systems

    • Which to use
    • Are any documented

  • Unit

    • When is it useful
    • How to use

  • Abstract Types

    • When is it useful
    • How to use

  • JBuilder

    • What is this
    • When is it useful
    • How to use

  • Modules

    • What is this
    • When is it useful
    • How to use

  • Functors

    • What is this
    • When is it useful
    • How to use

  • Objects

    • When is it useful
    • How to use

  • Classes

    • When is it useful
    • How to use

  • OCamllex

    • What is this
    • When is it useful
    • How to use

  • Menhir

    • What is this
    • When is it useful
    • How to use

  • Angstrom

    • What is this
    • When is it useful
    • How to use

  • OCaml FFI

    • What is this
    • When is it useful
    • How to use

  • Distributing Single Packaged Executable (like Go)

    • What is this
    • When is it useful
    • How to use

I know some of these topics have been written about, but people learn in different ways and even if it’s written once you may have a better perspective, grasp, or better teaching ability than maybe the original writer. Many people are really interested in these topics. I hope the OCaml community can spread, curate information on these topics whether it be through Guides, Tutorials, Blog Posts, etc and spread the word about this to everyone in the community and those interested. I hope this is motivating and constructive. Thank you everyone in the community who is trying to make OCaml more accessible and available to people in any way shape or form.

38 Likes
2

I agree with most of the points here. Just to point out ppx is a bit controversial at this point and some community members are leaning towards to have a concise set of ppx but no more than that.

Also, JBuilder should be mentioned in the above list. It is definitely going to be a big thing for the OCaml community.

3

This x1,000,000,000.

2 Likes
4

One thing I wish we would have in the OCaml community is someone to organize the community and write and improve the entry level documentation. A very good example is Steve Klabnik in the Rust community.

The quality of the official manual is one thing (it’s arid, but at least it does what it aims to) but the quality of the Learn section of ocaml.org is an absolute disaster.

There are various individuals doing a little bit in their free time or in some specific settings, and it’s great, but it’s not enough. And yes, I’m fully aware that having someone on the pay roll as “community manager and technical writer” is not completely trivial in most organizations (academia in particular).

6 Likes
5

Molding OCaml Manual into something similar to Rust’s Documentation would be a step in the right direction, it even has runnable examples: https://doc.rust-lang.org/book/first-edition/

5 Likes
6

I would absolutely love to have a chance to do this. I want OCaml to succeed. And there are so many other people just dying to contribute.

9 Likes
7

Do you know what tool they use?

8

For the manual, updating the css to a more modern feel should be quite doable. It would be better with a designer at the helm but otherwise I could probably achieve a least a basic flat theme.

1 Like
9

One thing that could be very useful to do would be to start a wikibook, like haskell has. Many times while learning haskell I found myself referring to the wikibook. The nice thing about this is that anyone can contribute.

I’m also really pro using Discord. It seems to be a huge success for ReasonML. Chat with multiple channels is really great, because it’s so easy to lose track of conversations in IRC.

In general, I expect the number of ReasonML programmers to quickly eclipse that of OCaml ones. They have the right technologies and the excitement. What happens then is anyone’s guess.

4 Likes
10

Thanks for the feedback! It’s always good to hear about experiences from people who are new to the environment.

A few quick thoughts about RWO and Jane Street packages.

  • RWO is definitely pitched at a high level. We intended the book to be for experienced software developers who didn’t happen to know OCaml or functional programming. It’s definitely not aimed at the middle-school/high-school set. That said, there are other books that are more introductory in nature. OCaml From the very beginning is a good choice there.
  • OCaml documentation is lacking in many places, in part because there is insufficient written docs, and in part because of tooling complications. That said, things are improving. odoc is a big step forward, and we’re working on getting high quality doc generation for our packages. We’re also actively working on hiring a technical writer to help build out our internal and external docs.
  • Your list of topics is great, and we hope to add some chapters to RWO once we finish the refresh, including coverage of GADTs, testing frameworks, and build systems. Some of the things you discuss (polymorphic variants, functors, objects, classes, modules) are already covered in RWO, though of course the coverage may not be to your taste.
  • We’re happy to collaborate with people on our packages, and have actually gotten quite a lot of contributions on jbuilder. We’re also working on improving our changelogs so that packages generated from our internal repos are easier to follow. The current situation isn’t perfect, but PRs against our repos are taken seriously.
    y
9 Likes
11

Excellent points Kevin. OCaml is getting a dose of fresh blood thanks to the projects that are trying to bring it into the web dev space (Js_of_ocaml, BuckleScript, Reason). Now’s a great time for all of us to step up and publicise it with great content and killer projects. I feel that the Reason community is leading the way on this. If they experience a pile-on effect from the JavaScript community, the Reason syntax may well end up becoming the dominant OCaml syntax.

Anyway, personally the single biggest thing I would love to see is a cross-platform project/build/dependency management tool like Cabal or Cargo. I know Opam and JBuilder are the current tools of choice but they seem to lack proper sandboxing. Bob Zhang has pretty much solved this in BuckleScript by just reusing the npm infrastructure for reproducible build management. I’d love to help OCaml achieve this but I don’t have much of an idea how.

2 Likes
12

Can’t anyone contribute to the OCaml manual right now, or to the ocaml.org documentation? What are the barriers to contribution there?

1 Like
13

The manual is not a place where people go to informally learn about OCaml. At least, our manual isn’t that way, and I’m not sure it should be. Adding to the manual requires going through a significant bikeshedding process, thus discouraging contribution.

ocaml.org has a similar problem. The granularity for contribution is coarse: one needs to write a whole tutorial before it’s up online and other people can contribute to it. In the meantime, one may need to justify the change in a git PR discussion, which sucks out all desire for writing. Additionally, making several changes involves the slow process of posting PRs and having them each approved. The github platform simply isn’t built for the crowdsourcing of lightweight documentation IMO.

A wiki doesn’t have this contribution barrier: anyone can contribute as much as they want, including incomplete material, which facilitates crowdsourcing. The change is instantaneous (but can be reversed as needed), allowing others to respond to the change immediately.

5 Likes
14

A quick question since I’ve never been to the ReasonML Discord: would it be a good idea to have two separate Discord servers for ReasonML and OCaml?

On the one hand, it would help avoid confusion between the two of them, but, on the other hand, a lot of topics are common, and having two places to look up answers might feel like a hassle.

Anyway, Discord being free, we can try and setup one, and see how it goes from there (kind of like this Discourse).

15

We have already have OCaml discussions on ReasonML discord server. I think more discussions are welcome. @jordwalke can speak more on the matter.

6 Likes
16

Yes, this is one of the very first points I see when beginning the book. The point I was trying to get across but that I think I failed at was that so many of the resources for OCaml can be made available to larger audiences if the some changes were made, in this case if the examples were to be tweaked.

1 Like
17

Thanks for bringing this up. I went through similar pains when I started learning OCaml recently, but have different thoughts on why that is so.

I found Real World OCaml to be a challenging read in places, but I would not want it any other way. It condenses insights from the authors’ vast experience without being very verbose about it. It felt to me as both an OCaml education as well as a programming education. The gaps were elsewhere.

As I was learning OCaml I went looking for codebases to see idioms and get a feel for how real-world projects are written, and the standard library didn’t do it. They make a lot of sense now that I have a basic understanding of the language, but what I then wanted was to see a fully functioning application, and Unison was the only large codebase I could find.

I also made the mistake of waiting too long before I got started with a real project. It was uncomfortable initially because I didn’t know what the right way to do things were. Some explicit assurances on what to expect would have helped. Like “you are going to do a lot of pattern matching; that’s normal”; “when in doubt, use a list, not an array”; “the recursion that you see everywhere exists for a purpose - you can’t iterate with purely functional code and immutable bindings” etc. (If I’m wrong with these statements, please correct!).

I think what the OCaml ecosystem misses are narratives. These can be tutorials like “Building a tiny web server with OCaml”, or “A CLI todo list in OCaml”, or cookbooks like “How to create a tree from a flat list”, “How to walk a directory tree”, or experience reports like “How I made my imperative OCaml code functional”, “How we handle 10mb of big data with OCaml”, or tips and tricks like “When to use an Array over a List”, “The perfect use case for polymorphic variants” etc.

This gap will be filled as the community grows, and our presence here is proof that it is happening. For good or for bad, a large mass of programmers today make their livelihood by building things on the web, and they cannot use a language unless it runs on the browser. I can see Reason picking up steam among this crowd, of which I’m part of. There are already Reason meetups happening around the world, and I’m hoping we’ll start hearing about commercial adoption by next year. We are used to sharing over the web, and expect it as a matter of course, and so will hopefully fill the documentation gap when we realize there is ample opportunity here.

What I’m trying to say is that good documentation is not a prerequisite for a large community to form, but rather documentation comes after the community. And a community grows because of external catalysts - an urgent need that it fixes that people don’t have a choice but to deal with incomplete documentation for a while - like Rails making web development easy and making Ruby popular. Or React which solved the front-end conundrum well. For OCaml, it feels like it’ll be the ever-increasing complexity of user interfaces, and so BuckleScript and Reason.

12 Likes
18

The problem with just joining the ReasonML discord server is that it’s really oriented towards ReasonML-based topics. I suspect most people interested in OCaml aren’t interested in the same things ReasonML people find interesting. It would take quite a few changes to make the ReasonML discord server comfortable for OCaml programmers.

3 Likes
19

If you’re looking for examples of complete programs designed for beginners, you might find this repo helpful:

https://bitbucket.org/yminsky/core-hello-world

5 Likes
20

In day-to-day operation it’s not a problem. There’s an #ocaml channel (among others) and people discuss different topics with no issues as far as I can tell.

1 Like