Update the docs section on OCaml on Windows
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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