search

ocaml-explore / explore

Explore OCaml is a centralised source of workflows for being productive with OCaml using the OCaml Platform
https://ocaml-explore.netlify.app
44 stars 3 forks source link

Some suggestions for Workflow renaming and management #39

Open rudradesai200 opened 4 years ago

rudradesai200 commented 4 years ago

As discussed with @patricoferris , These are some of our suggestions

  1. Rename the "Configuring Ocaml tools for your Editor" To "Setting up an OCaml development environment" would be more appropriate and we can also add a few more headings under this workflow like

    • Generally Required Libraries
    • Files and Libraries Management (Included in Navigating through OCaml Projects) etc

  2. Add a sitemap for the website, or we can add a search bar to help new users navigate through the website more efficiently.

  3. There are already separate pages for tools like opam and dune, but a good-explanation involving the use of top-level in jupyter-notebook, bytecode compiler and the assembly compiler can be helpful. Also, I found that the explanation for library management using dune and opam is not present for complete beginners. Some common problems faced by some of my colleagues and even me were

    • Handling multiple modules and libraries,
    • Handling functors and separating execuatables
    • creating multiple tests for the same modules etc

I am also attaching some references which I found to be quite useful for setups and other tools.

  1. Starting an ocaml app project using dune
  2. Using files to separate modules and programs
patricoferris commented 4 years ago

Thanks @rudradesai200 for these great suggestions!

I've split out the first two into separate issues as I think they raise great points. As for the third, the problems you and your colleagues had is exactly the things we should mitigate whenever it falls in our remit.

Library Management

I think the "library management with opam and dune" is somewhat covered in a... decentralised way across multiple pages for example:

Is this the kind of content you were thinking of? Do you think a "Installing and using libraries" workflow would be a better place to bring these ideas together?

I think it might be. I think some of the hurdles most (including myself) struggle with are:

Other Problems

I think, as you have pointed out, modules and functors is covered by RWO very well and are more concerned with aspects of the OCaml language rather than workflows for being productive in the language.

However, there is also a concept that has come up time and time again about "Design Patterns" in OCaml which I believe you are eluding to which isn't covered as much in RWO. For example how Irmin uses a lot of functors. I'm not sure it is suited for Explore either as it is v. subjective and project dependent. Is this what you mean? Or am I missing something?

rudradesai200 commented 4 years ago

"Do you think a "Installing and using libraries" workflow would be a better place to bring these ideas together?" Yes, I completely agree with you. This workflow could indeed resolve most of the issues faced by beginners like me. Also, I have not yet properly explored the Switches and Pinning part myself, to be honest. Let me get back to you on this.

I am currently learning Library and File management in OCaml and interaction between dune and opam, as I explored OCaml using Jupyter Notebooks only. So, I will start creating a rough design about what we can include in this workflow, and maybe we can review it later. What do you think?

"I'm not sure it is suited for Explore either as it is v. subjective and project dependent. Is this what you mean? Or am I missing something?" Yes, I agree it is very subjective as well as project dependent. The problems which I was facing was mainly concerned with "Interaction between dune and opam", and we are already covering it above, so no worries.

Also, I am mostly done with the beginner's workflow as of now, I must say you guys have done really impressive work. This project is more than sufficient enough for beginners to get started with OCaml.

patricoferris commented 4 years ago

Great sounds like a plan! Once you are ready, feel free to open a third issue for creating that workflow to track it separately and we'll review it :) Thanks again for all of the wonderful suggestions!

patricoferris commented 4 years ago

Evidence that this a needed resource: