You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
So, on global-installation, it's really not clear what to do if you already have a global / functioning OCaml setup on the machine in question (specifically, I mean an OPAM switch with ocamlmerlin installed).
(I'm a special-case; I'm trying to contribute back to Merlin's support for Vim; my installation is global to the machine, from my source clone of the project, but same question basically applies.)
In fact, in general, the onboarding is much clearer / smoother coming ‘from the JS direction.’ I totally understand this — more devs in your target-market are coming from Node / JS / our community; but I'd wager that Reason has matured enough that it's time to start fleshing out the docs for these cases a little more? “Definitely not an edge-case, but also not the single largest class of users”-type documentation?
Anyway: tl;dr, I suggest sections on the following pages, documenting the steps specifically for users who already have some sort of functioning OCaml setup, to bring OCaml up to ‘welcomeness-parity’ with JavaScript:
reasonml/quickstart — I'd say a bullet-point about OCaml users belongs on this page, the very first one linked from the homepage
reasonml/global-installation — I can deduce from this page that the reason-cli npm module installs a special version of Merlin, and that it's specifically an old version. This should be made explicit: “Here's how to install the correct versions of Merlin et al. in an OPAM switch …”
reasonml/convert-from-ocaml — although I'm new, I have been writing OCaml for a bit over a year now, and I've never once invoked ocamlbuild directly. This page desperately needs a section on existing build-systems, that mentions Dune and Oasis! (=
… not this project, but as far as I'm aware, these projects are tightly integrated, so I figured I'd keep the Issue centralized:
bucklescript/installation — needs a non-‘Install From Source’ section under ‘advanced users’ focused on OPAM as an alternative to npm
I hope this feedback was helpful! I'm a member of both communities (Node contributor since 2009; newer to OCaml, but came separately from Reason), and I'm coming to Reason as a complete newbie … so I hope I have a useful / unique perspective on what's missing from y'all's documentation!
The text was updated successfully, but these errors were encountered:
One thing in particular — forgive me if I end up using this Issue as a sort of running-log of my experiments and the documentation problems I run into while getting started — is that I can't figure out how to install BuckleScript, in a way that I can follow along with any of the documentation, without going through npm — specifically, npm install bs-platform. There's 4.02.3+buckle-master, but that seems undocumented?
So, on global-installation, it's really not clear what to do if you already have a global / functioning OCaml setup on the machine in question (specifically, I mean an OPAM switch with
ocamlmerlin
installed).(I'm a special-case; I'm trying to contribute back to Merlin's support for Vim; my installation is global to the machine, from my source clone of the project, but same question basically applies.)
In fact, in general, the onboarding is much clearer / smoother coming ‘from the JS direction.’ I totally understand this — more devs in your target-market are coming from Node / JS / our community; but I'd wager that Reason has matured enough that it's time to start fleshing out the docs for these cases a little more? “Definitely not an edge-case, but also not the single largest class of users”-type documentation?
Anyway: tl;dr, I suggest sections on the following pages, documenting the steps specifically for users who already have some sort of functioning OCaml setup, to bring OCaml up to ‘welcomeness-parity’ with JavaScript:
reason-cli
npm module installs a special version of Merlin, and that it's specifically an old version. This should be made explicit: “Here's how to install the correct versions of Merlin et al. in an OPAM switch …”ocamlbuild
directly. This page desperately needs a section on existing build-systems, that mentions Dune and Oasis!(=
… not this project, but as far as I'm aware, these projects are tightly integrated, so I figured I'd keep the Issue centralized:
I hope this feedback was helpful! I'm a member of both communities (Node contributor since 2009; newer to OCaml, but came separately from Reason), and I'm coming to Reason as a complete newbie … so I hope I have a useful / unique perspective on what's missing from y'all's documentation!
The text was updated successfully, but these errors were encountered: