ocaml / ocaml/ocaml.org

Update the docs section on OCaml on Windows

Open
#2,139 9 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Markdown
Stars
192
Forks
389
Avg merge
23h 8m
Merged PRs (30d)
20

Description

I've already discussed this with a few of "the Windows folks" (in particular, @jonahbeckford for Diskuv and @kit-ty-kate for opam 2.2), and we all seem to agree.

Currently, the section on OCaml on Windows opens with

There is a new Diskuv OCaml ("DKML") Windows installer that we recommend for new users.

That makes a lot of newcomers on Windows try their luck and get stuck with native Windows support. Later in the docs, there's a sub-section about WSL2, saying

If you only need to run OCaml programs on a Windows machine, the simplest solution is to use the Windows Subsystem for Linux 2 (WSL2).

However, that's too easy to miss and to misunderstand given the introductory sentence about Diskuv being the officially recommended approach for newcomers.

Suggestion

Let's start the section saying that for newcomers, we recommend using WSL2. For people in one of the following situations, we recommend trying a native approach: For people who want to distribute OCaml apps on Windows; for people who're really into Windows from a perspective of technical curiosity; or for advanced programmers who're happy to try native Windows support from the beginning on

Then, the first sub-section should be about WSL2 and the second sub-section about native Windows support: Diskuv, opam 2.2, installation environments. It should be clear that the second sub-section is a different thing and won't be needed for newcomers who just want to use OCaml without e.g. distributing apps in Windows!

Video tutorial about Windows OCaml set-up with WSL2

@PizieDust has made a very nice tutorial explaining how to set-up OCaml on Windows with WSL2 🎉 There are a lot of questionnaires showing that people prefer to watch a video rather than reading through instructions. So I also suggest linking to that video!

@patricoferris can upload it to the Outreachy channel of watch.ocaml.org. That might be a little confusing, though, as it's not actually related to Outrachy. Does anyone have access to a more general watch.ocaml.org channel and wants to upload it there?

Opam 2.2

Once native Windows support via opam 2.2 is tested enough by non-newcomers and we have a clear and short list of packages with potential issues on Windows, we should update the page again to explain how to use OCaml on Windows directly.

Concrete context

Every single Outreachy round, the vast majority of OCaml set-up problems/questions are about problems on Windows. They're asked by applicants who instead of reading our advice to use WSL2, read the advice on ocaml.org to use Diskuv. The Outreachy summer 2024 round has started yesterday. If we can make this change quickly, we can still avoid leading too many applicants down this "rabbit hole" ("rabbit hole" from a newcomer's perspective).

Does that sound good? If so, do you (the ocaml.org maintainers) want to make that update to the page or do you want one of us (@PizieDust , @patricoferris or me) to do it?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open the OCaml on Windows page linked in the issue and compare its introduction and subsection order with the requested newcomer guidance. Update the page to foreground WSL2, separate native Windows support, and include the linked WSL2 video; done means the page clearly distinguishes these paths and explains who should use each.

Written by the indexing model from the issue text.

Assessment

Tech stack
ocaml
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.