Update the docs section on OCaml on Windows #2139
Comments
|
Just as a note: here are the different pages which contain setup instructions:
The third url above is a pretty interesting one. Here's a note from it about WSL2 https://ocaml.org/docs/ocaml-on-windows#wsl2:
Given that this is already indicated, however, not on the main install page. Still on the page, there's a section on how to connect VScode to WSL. |
That hasn't been true for a couple years. It is just an outdated statement from when the only options were Cygwin (pre opam 2.2) and WSL2. More Details Using WSL2 (and to some extent Cygwin) has a pre-requisite that the user already knows Unix. Instead of point-and-click (the normal experience on Windows for Java, C#, etc.) you get to teach them how to use the Unix command line (examples: opam 2.2 (and DkML) do a great job of hiding the Unix prerequisites from the Windows users. Asking a Windows newcomer to learn a new operating system just to learn a new programming language is not and will never be the "simplest solution". |
|
Aside: I realize the links and instructions for DkML are still using the wrong version (1.2.0) versus the current (2.1.0). Should I open a new issue or just fold it here? It should be: Full instructions at https://gitlab.com/dkml/distributions/dkml/-/releases/2.1.0#new-install-steps TLDR: winget install Microsoft.VisualStudio.2019.BuildTools --override "--wait --passive --installPath C:\VS --addProductLang En-us --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
winget install Git.Git
winget install Diskuv.OCamlAnd then in a new terminal: dkml init --system |
|
@jonahbeckford: Yes an issue on updated instructions for DKML 2.1.0 would be helpful. Another about the outdated text on WSL would be too |
|
@jonahbeckford , I've understood you wrongly in our short conversation on slack then. I won't insist on recommending WSL2, if you're against it. What I now understand from your message here is that you're against recommending WSL2 for newcomers. If you confirm that, let me know and I close the issue. The reason why we want to recommend WSL2 for newcomers (only for newcomers!) is the following. For context for my reasoning: Outreachy is a grant for people with little to medium experience in programming/computers to work on open-source projects. During the application period for those grants, a lot of people try to set up OCaml to apply for a grant to work on OCaml projects. For folks on Windows, we always recommend WSL2. Nobody has ever had serious trouble getting things up and running with WSL2. However, some people read the ocaml.org docs instead of reading our recommendation, and try native Windows. So far, we haven't had even one single person who's been successful with that. I admit that those people are really newcomers. For people who are familiar with handling system things on Windows, the experience is probably very different and I'm sure, once it's set up, it's very pleasant. So, long story short, we've seen a lot of newcomers trying to set up OCaml on Windows. WSL2 always works, and googling a few unix commands really doesn't seem to be a problem for newcomers: There's not much muscle memory for Windows commands yet and writing I don't have Windows myself, so I can't give examples of what can go wrong with Diskuv. @PizieDust, do you happen to have some example? Btw, having to adapt to Unix commands is for sure a very good point in favor of native windows, which I had missed! So far, my list of people who should use native Windows instead of WSL2 has been
In the case that we do want to recommend WSL2 on ocaml.org for newcomers, we should certainly add
|
|
I love that you have some solid data points about WSL2. I've seen contradicting data points on WSL2. So I'm going to guess why:
==> If someone has a Unix friend or mentor they definitely should be using WSL2. Using native Windows would in fact be grossly unfair to the Unix friend/mentor. It would be great if that were called out explicitly.
Yikes. But also that is DkML 1 and not DkML 2 ... the instructions have not been updated as I mentioned earlier. Also, if there are 50 people who have tried but not succeeded, why haven't any issues been opened with DkML? https://github.com/diskuv/dkml-installer-ocaml/issues has 100 issues (and more from other queues). Really puzzled that 50 people can install and have failures and me not know about it. And if my memory serves me correctly, anyone who has had an installation issue with DkML 1 does not have an issue with DkML 2. But I can't fix what I don't know is broken. ==> Please please please have someone file an issue. ==> For now, if that number is accurate (~50) with zero success for DkML or Cygwin then this is an easy discussion! Just take down DkML and Cygwin options from the main page.
The difference between Windows and Linux is more than a single command. Without a Unix mentor, where is the Windows newcomer supposed to go when they get stuck or confused? ==> I'm sure there is a YouTube video somewhere to gently introduce Linux. Quick search led to https://www.youtube.com/watch?v=wcdquhB6hT8. I haven't watched more than the first minute but that could be OK. |
|
Thanks for being open to discussing/chatting about this! About the contradicting points about WSL2 experience:
Indeed, as far as I know, only very few Outreachy mentors so far use Windows. And the very few mentors who do are former interns and use WSL2 themselves. It's a vicious cycle in a way.
Outreachy doesn't require interns to be enrolled at a college/university. But yes, the experience level on average is similar to upper-year college/university students. So, it's people
This is a very good point and could happen to Outreachy applicants/interns. Do you know what the minimal hardware requirements are for WSL2 to work well?
Nowadays, one of those mentors/friends is likely going to be ChatGPT ;) More seriously: For people with a certain level of experience, it's not too hard to find the Unix commands they need online (I do see how for highschool students that's likely not the case, though, as they're not as trained to be autonomous, yet). Finding enough info online to fix OCaml native Windows problems, is a lot harder than finding info about Unix commands. However, again, this is a vicious cycle: Not many people use OCaml natively on Windows, so not much info online, so not many people use it etc. So I do understand as well that we'll at some point need to break that cycle. However, I think it's better to do that step-by-step rather than fully recommending native Windows support on ocaml.org no matter who the target is.
Good point... Could you update them? Apart from this concrete example, we need to find a way to ensure that the ocaml.org docs are up-to-date in general! @sabine, @cuihtlauac, do you already have plans/ideas around that? I guess the first step is to have a concrete overview of everything that's being recommended on ocaml.org, particularly everything that we expect to get outdated some day, e.g.
Does such a list already exist? Good point about filing issues as well. I'd say that's at least partly on us (the mentors/organizers): As we don't know which issues are on DkML and which are on the applicants not having read something, we always just tell them to use WSL2, where we can help. We should at least tell them to open an issue before moving to WSL2.
I didn't suggest to totally take it down from the ocaml.org page! I'm just suggesting to make clear what the ups and downs are between DkML and WSL2 are. Ups for DkML: You have Windows commands available, you can build native binaries, you need fewer resources, there're fewer indirections. Ups for WSL2: Easier set-up, easier to debug / more info online than on DkML, probably (?) more reliable (I assume there are still libraries/tools that are simply not natively Windows compatible yet, aren't there?). It's really a pity that the current Outreachy round is already 2 weeks in. If I had been quicker on this, we could have asked this round's applicants to use DkML 2, see if they also run into issues on version 2 and, if so, asking them to file them! Sorry that we're late for that now. Given that it's too late for that now and given that I have no idea whether people run into similar problems on DkML 2 as on DkML 1 or not, what about the following? We keep on recommending DkML at the top of the Windows section. But
Wdyt about that, @jonahbeckford, @cuihtlauac? Btw, @PizieDust , just in case you're looking for new communication content: I think if you'd want to try DkML 2 and make a set-up tutorial about that as well, that'd probably be very valuable. @jonahbeckford , let us know if you think differently. (Next time, I'll try to keep my answer shorter ;)) |
|
We don't currently have any lists around content that can become outdated. It might be a good idea to have that, but tbh, I would lose that list. |
|
I’m fine with the plan!
Get Outlook for iOS<https://aka.ms/o0ukef>
…________________________________
From: sabine ***@***.***>
Sent: Thursday, March 21, 2024 8:19:45 AM
To: ocaml/ocaml.org ***@***.***>
Cc: Jonah Beckford ***@***.***>; Mention ***@***.***>
Subject: Re: [ocaml/ocaml.org] Update the docs section on OCaml on Windows (Issue #2139)
We don't currently have any lists around content that can become outdated. It might be a good idea to have that, but tbh, I would lose that list.
—
Reply to this email directly, view it on GitHub<#2139 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AREG4PNKEWWHVWRQYTPDYITYZL3BDAVCNFSM6AAAAABEHWX7VGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMJSGYYDGMZXHE>.
You are receiving this because you were mentioned.Message ID: ***@***.***>
|
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
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
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?
The text was updated successfully, but these errors were encountered: