Improve the tutorials

[pitag-ha]

This would be a good first issue for anyone looking to get started improving and contributing to OCaml.org. In particular, this issue would be great for someone interested in OCaml but with with no or little experience in it.

The tutorials in Home -> Learn -> OCaml Tutorials are meant for people with no or little experience in OCaml. I suggest that someone with no or little experience goes through the first section or part of it to see if everything is easily understandable and coherent:

This is a very valuable issue that doesn't require coding but being proactive. Don't hesitate at any moment to ask here on the issue if there's something you'd like to improve in the tutorial, but don't know how.

Two possible suggestions:

• in Up and Running: would the follwowing be better positioned if it came right after the code snippet including dune init exe helloworld or is it good where it is?

• in Basics: is the following part (starting at "Using let (without rec)...") easily understandable?

[Ndipbanyan]

Hi @patricoferris @pitag-ha I will like to take on this issue

[pitag-ha]

@Ndipbanyan , great :) don't hesitate to ask questions here when you are unsure.

[Srinithyee]

Hi @pitag-ha I am a beginner in OCaml. I am looking for some good first issues as a part of my Outreachy application. Looks like most of the beginner issues have been assigned. It would be great if you could suggest some issues I can work on. Thanks!

[Ndipbanyan]

@Ndipbanyan , great :) don't hesitate to ask questions here when you are unsure.

Sure I will thanks @pitag-ha

[Srinithyee]

@Ndipbanyan have you been assigned this issue? or can I also work on it?

[pitag-ha]

Hi @Srinithyee

Hi @pitag-ha I am a beginner in OCaml. I am looking for some good first issues as a part of my Outreachy application. Looks like most of the beginner issues have been assigned. It would be great if you could suggest some issues I can work on. Thanks!

A good place to state that you're interested in contributing but can't find a good issue is here. One usually tries to restrict the conversation on an issue to topics related to the issue.

@Ndipbanyan have you been assigned this issue? or can I also work on it?

I think @Ndipbanyan has stated their interest pretty clearly when saying "I will like to take on this issue". You can read more about issue "assignment" here.

Are you particularly interested in improving the tutorials or generally in any kind of contribution? If it is about the tutorials, we can try to find you other tutorials to work on than the ones of this issue.

[Srinithyee]

@pitag-ha Thanks for the heads up. I am looking for any contribution in general. I thought tutorials would be an easy way to start, since I've had no prior experience with Ocaml. Thanks for the link as well. I will try commenting and looking for some new issues there. Sorry about initiating this conversation under the issue.

[Ndipbanyan]

@Ndipbanyan , great :) don't hesitate to ask questions here when you are unsure.

@pitag-ha I went through the Up and Running and The Basics pages as someone with no experience in OCaml and have the following to say and will like to make changes :

• In Up and Running using Next instead of Then here

makes it clearer for the user to understand the next step to take after the previous one.

• Also, this

will be better positioned if it came right after the code snippet including dune init exe helloworld because it will enhance the flow of the instructions better than the position which it is currently positioned.

• In Basics: "Using let (without rec)..." is easily understandable.

So in trying to effect these changes, I believe I am to simply click on the pen in the top right corner of the page that will redirect me to that page on GitHub where I can edit it and submit my changes right?

[Ndipbanyan]

@Ndipbanyan , great :) don't hesitate to ask questions here when you are unsure.

@pitag-ha I went through the Up and Running and The Basics pages as someone with no experience in OCaml and have the following to say and will like to make changes :

• In Up and Running using Next instead of Then here

makes it clearer for the user to understand the next step to take after the previous one.

• Also, this

will be better positioned if it came right after the code snippet including dune init exe helloworld because it will enhance the flow of the instructions better than the position which it is currently positioned.

• In Basics: "Using let (without rec)..." is easily understandable.

So in trying to effect these changes, I believe I am to simply click on the pen in the top right corner of the page that will redirect me to that page on GitHub where I can edit it and submit my changes right?

@patricoferris @pitag-ha still waiting for clarification and approval to move on with this. Please reply if you have the time. Thanks.

[pitag-ha]

Thanks, it's great to see that it's all so well understandable!

using Next instead of Then

I don't think it's worth opening a PR for such a small change.

because it will enhance the flow of the instructions better than the position which it is currently positioned.

That's also a good reason. I head the following reason in mind: at the moment the ls snippet comes after the advice to run dune build. After running dune build, the folder will contain more then _build, dune and helloworld.ml (as in the snippet): it will also contain the dune-project. But if that didn't bother you, I don't think it's important to change.

It's already valuable to know that there isn't much to improve in the first 2 subsections. Thanks for that!

[Ndipbanyan]

Alright then @pitag-ha