{"id":16717498,"url":"https://github.com/firobe/ocaml-platform-doc","last_synced_at":"2026-01-03T03:10:19.915Z","repository":{"id":74791623,"uuid":"548770651","full_name":"Firobe/ocaml-platform-doc","owner":"Firobe","description":null,"archived":false,"fork":false,"pushed_at":"2022-10-11T12:13:04.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-22T00:37:19.497Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Firobe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-10T06:44:57.000Z","updated_at":"2022-10-10T10:32:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"f4861531-97f0-435d-b360-ed0e892615c2","html_url":"https://github.com/Firobe/ocaml-platform-doc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Firobe%2Focaml-platform-doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Firobe%2Focaml-platform-doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Firobe%2Focaml-platform-doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Firobe%2Focaml-platform-doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Firobe","download_url":"https://codeload.github.com/Firobe/ocaml-platform-doc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243713402,"owners_count":20335566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-12T21:32:10.026Z","updated_at":"2026-01-03T03:10:14.874Z","avatar_url":"https://github.com/Firobe.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\ntitle: Documentation overview of the OCaml platform\n---\n\nThis is an overview of the available resources, both official and not,\nto understand and use the main tools of the OCaml platform. The goal is\nto assess the current state of the documentation, and decide what\nimprovements should be prioritized. The list tries to be exhaustive for\nofficial resources, but is not exhaustive for non-official resources\nalthough it tries to include significant/useful external resources (such\nas Real World OCaml).\n\nThe tools are roughly ordered in decreasing importance order (an\nunderstanding of the tools near the top is absolutely necessary to be\nproductive in OCaml).\n\nAll resources are roughly categorized according to the\n[Diátaxis](https://diataxis.fr/) documentation framework along the axes\nof practial/theoretical and learning/working. Furthermore, for category\na resource can be rated 🟢, 🟡 or 🔴 according to these (arbitrary, vague\nand subjective) criteria:\n\n- 🟢 for resources that are complete, up-to-date and well-written;\n\n- 🟡 for resources that are not complete enough, or are austere to\n beginners;\n\n- 🔴 for resources that are out of date, or exist but with only the\n bare minimum of information, or are very hard to navigate.\n\nResources in **bold** are official ones: either written/published by the\nauthors of the tool or under the \u003chttps://ocaml.org\u003e domain.\n\n| Tool | Resource | Reference | Explanation | Tutorial | How-to guide | Notes |\n|:-------------:|:-------------------------------------------------------------------------------------------------------------|:---------:|:-----------:|:--------:|:------------:|:-------------------------------------------------------------------------------------------------------------------------------|\n| `opam` | **[Manual](https://opam.ocaml.org/doc/Manual.html)** | 🟢 | 🟡 |   |   | Lacks a bit of structure |\n| | **[Usage](https://opam.ocaml.org/doc/Usage.html)** |   |   | 🔴 |   | Structured more like a reference than a good entry point |\n| | **[FAQ](https://opam.ocaml.org/doc/FAQ.html)** |   |   |   | 🟡 | |\n| | **[Up and running](https://ocaml.org/docs/up-and-running)** |   | 🟡 | 🟢 |   | Not hosted on the opam website: lacks visibility |\n| | *Overall official* | 🟢 | 🟡 | 🟡 | 🟡 | **Lack of clear entry point for beginners with concepts explained** |\n| | [Real World OCaml Ch.21](https://dev.realworldocaml.org/platform.html) |   | 🟢 | 🟢 |   | |\n| `dune` | **[Manual](https://dune.readthedocs.io/en/stable/index.html)** | 🟡 | 🟡 |   | 🟡 | The structure is a bit all over the place |\n| | **[Quick start](https://dune.readthedocs.io/en/latest/quick-start.html)** |   | 🟡 | 🟢 |   | |\n| | **[Introduction video](https://www.youtube.com/watch?v=BNZhmMAJarw)** |   |   | 🟡 |   | A bit outdated |\n| | *Overall official* | 🟢 | 🟡 | 🟡 | 🟡 | **The ocamlverse tutorial below should be official** |\n| | [OCamlverse quickstart](https://ocamlverse.net/content/quickstart_ocaml_project_dune.html) |   | 🟢 | 🟢 |   | |\n| | [Real World OCaml Ch.21](https://dev.realworldocaml.org/platform.html) |   | 🟡 | 🟡 |   | |\n| `merlin` | **[Github Wiki](https://github.com/ocaml/merlin/wiki)** | 🔴 |   | 🟡 |   | List of commands not documented. User lost after editor setup. |\n| | **[OCaml github.io](https://ocaml.github.io/merlin/)** | 🟡 |   | 🟢 |   | Nice style but lacks visibility! |\n| | *Overall official* | 🟡 |   | 🟢 |   | **The gihub.io should be linked from the wiki or somewhere visible. The wiki needs some structure.** |\n| | [OCamlverse editor setup](https://ocamlverse.net/content/editor_setup.html) |   |   | 🟡 |   | |\n| `ocaml-lsp` | **[README+docs/](https://github.com/ocaml/ocaml-lsp)** | 🔴 | 🔴 | 🔴 |   | No structure, information sometimes outdated, no editor setup instructions. |\n| | **[OCaml Platform Extension](https://marketplace.visualstudio.com/items?itemName=ocamllabs.ocaml-platform)** | 🟢 | 🟡 | 🟢 |   | Good for VS Code |\n| | *Overall official* | 🟡 | 🟡 | 🟡 |   | **Good if using VS Code (though the extension could be more visible). Other users are left on their own (or assuming merlin)** |\n| `utop` | **[README](https://github.com/ocaml-community/utop)** | 🟡 | 🔴 | 🔴 | 🟢 | Good for installation, configuration. But you need to know how the general toplevel works. |\n| | **[API](https://ocaml-community.github.io/utop/utop/index.html)** | 🟢 |   |   |   | |\n| | *Overall official* | 🟢 | 🔴 | 🟡 | 🟢 | **Well documented but could link to resources explaining toplevel usage** |\n| | [OCamlverse toplevel](https://ocamlverse.net/content/toplevel.html) |   | 🟢 | 🟡 |   | Introduction to the generic toplevel |\n| `ocamlformat` | **[Main page](https://ocaml.org/p/ocamlformat/0.24.1/doc/index.html)** | 🟡 | 🟡 | 🟢 | 🟢 | |\n| | *Overall official* | 🟡 | 🟡 | 🟢 | 🟢 | **The CLI manual is the only complete reference for options** |\n| | [Real World OCaml Ch.21](https://dev.realworldocaml.org/platform.html) |   |   | 🟡 | 🟡 | |\n| `odoc` | **[Main page](https://ocaml.github.io/odoc/)** | 🟢 | 🟢 | 🟢 | 🟢 | **Very well documented** |\n\nFurthermore, there are a few resources introducing the whole platform\nand the interactions between some of the different tools:\n\n- **[OCaml best practices](https://ocaml.org/docs/best-practices)**\n\n- **[OCaml up and running](https://ocaml.org/docs/up-and-running)**\n\n- [Real World OCaml\n Ch.21](https://dev.realworldocaml.org/platform.html)\n\n- [Tim’s \"Getting Started with OCaml in\n 2021\"](https://lambdafoo.com/posts/2021-10-29-getting-started-with-ocaml.html)\n\nOverall one of the biggest problems for beginners is the segmentation of\nthe documentation. Even amonst official resources and for the same tool,\ndocumentation lives on:\n\n- \u003chttps://ocaml.org/docs/\u003e\n\n- \u003chttps://ocaml.github.io\u003e\n\n- \u003chttps://opam.ocaml.org\u003e\n\n- \u003chttps://dune.readthedocs.io\u003e\n\n- the Github pages of the tools\n\nExcept when reading a course (such as Real World OCaml), a beginner will\nmost likely learn about a single tool without seeing the big picture of\nthe OCaml tooling. The [OCaml platform](https://ocaml.org/docs/platform)\npage gives it blessing to a selection of tools but then leaves users on\ntheir own to figure out how to install and use each tool.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirobe%2Focaml-platform-doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirobe%2Focaml-platform-doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirobe%2Focaml-platform-doc/lists"}