search

ocaml-toml / To.ml

OCaml library for TOML
https://ocaml-toml.github.io/To.ml
Other
82 stars 20 forks source link

README should be beginners friendly #23

Closed mackwic closed 8 years ago

mackwic commented 9 years ago

We shouldn't assume that the reader is an expert in ocaml.

We need to add some pointers to ocaml resources so that beginners will not be lost. Some ideas:

Input welcome

sagotch commented 9 years ago

People using this library are expected to know some OCaml, so there is no need for me to introduce OCaml language nor there is to point any tutorial to learn it.

OCaml beginners would probably already know about these links, and if they do not, the first google page would bring them to them.

Even worst, I think it would only add useless text/information they already know for users.

mackwic commented 9 years ago

That's an interesting point of view. Even more interesting that I strongly disagree and never understood this kind of assumptions. Let's debate.

Here is my point of view:

From there I think that:

</nicely-arguemented-point-of-view> <ocaml-rant>

Also, there is all the ocaml mess, that to say: the top-level diversity, the whole findlib (wtf is this?), cm(x)?{a,i,o,s,t,x}, and the choice ocamlbuild/OcamlMakefile/Omake/Makefile/Oasis (today ocamlbuild win the battle, but not everybody is aware of that). Thanks the ocaml legacy. All of that is really hard to understand for newcomers, and even skilled ocamlers barely knows the difference between a cmxa and a cma. Some could be genuinely interested by resources we can bring.

On a side-note, I never use top-levels, this stuff is simply too complicated relatively to what it can do (ever used ruby's pry or python's ipython ? Rstudio ?). Also, Ocamlbuild is still half-backed and mostly undocumented (see the hack in _tags I had to use in the oasis PR because of an ocamlbuild bug). Noone knows the Eclipse OcamIDE (which beats TypeRex in term of usability / features ratio from my PoV). Etc.

Summary of what I am tihnking: ocaml is a tough world. Don't make it tougher. :wink:

Emm commented 9 years ago

IMHO, a one or two sentences introducing OCaml wouldn't hurt, considering the popularity (or lack thereof) of the language. And then a link to a good OCaml tutorial or three.

sagotch commented 9 years ago

One or two sentences introducing OCaml is OK, but would not bring any useful information because it is not enough.

My point is: if someone actually read the README of toml, it is likely that it is a user of OCaml, and what are we supposed to teach him? Just how to use the library. Maybe he is not a OCaml user, so he must followed the bad link and won't read further as soon as he will notice it. Even if he finally shows interest for OCaml, google will help him better than we would do. I never saw a library teaching the language it uses.

I think that a tutorial, with side explanations on how to link using ocamlbuild (for instance), or how the ppx_deriving thing works would be more adapted.

amirmc commented 9 years ago

Hi folks, I just came across this issue so I thought I'd add my 2cents (as both an OCaml.org maintainer and a member of the MirageOS team).

I see you've already added some links but there are a few questions I'd encourage you to think about:

Overall, while I think it's noble to have pointers to learning resources, I agree with sagotch. People are not finding this repo by accident so they either (1) believe they know enough OCaml already or (2) are looking for actual code to browse through and learn from. For the former, the links to learning resources are unnecessary whereas for the the latter, I'd strongly argue that well documented/tested code is far more valuable. In addition, if you go down the route of adding more learning resources, then this repo is no longer about TOML.

Since the intent is to help newcomers, my suggestions would be the following:

I applaud the effort to help newcomers and I really think this is best done by creating a vibrant and growing ecosystem around OCaml. This includes learning resources (books & tutorials), good libraries/tools (well documented and well tested) and widely accepted working practices (cf OPAM, OCaml.org, etc). Each of these is somewhat distinct and IMHO each should aim to excel in their own areas.

Of course, you are free to do as you choose. I just wanted to share my thoughts in the hope of persuading you :)

sagotch commented 9 years ago

First, thank you for these thoughts. It is nice to have a new point of view.

Have only one link to point newcomers to OCaml.org (either the learn page or the books page) -- if you feel the information there isn't relevant, then please help us fix it!

Agreed. A lighter README would be more user-friendly instead of beginners-friendly. I think 1/3 of the README's length is composed by TOC and links for beginners, which I do not think to be the target of the library.

Have well documented code for To.ml with examples.

Writing a tool to manage toml file from command line and use it as a tutorial / example is on my TODO list, but a lot of things are...

Make those docs available online and linked from the README (see the alpha release of 'codoc' for some new tools). I can see by inspection that you already have docs online but I had to manually navigate there (it's not linked from the README).

I just added a link to gh-pages branch on the README. Also, it would be nice to change the project description on github to have it directly linked here instead of TOML's page, but I can not do it @mackwic .

Emm commented 9 years ago

I'm fine with limiting the "beginner space" in the README. I'll point out, though, that it's entirely possible to find the library by looking for a "TOML parser", so people won't necessarily be acquainted with OCaml.