[Caml-list] Is OCaml for experienced beginners?

[Caml-list] Is OCaml for experienced beginners?

[Hendrik Boom]

# Is anyone in charge of the OCaml ecosystem?

I am a beginner to OCaml.  I'm not a beginner to the functional style of programmins, nor to sophisticated type systems, nor to  computing in general.  I started programming in 1963, was involved with Algol 68, Lisp, and constructive type theory.  I've managed to get code running in the days when you had to enter it as numbers; the machine I  used then wouldn't even type letters other than u, v, w, x, y, z (its version of hexadecimal).  In those days what you needed to know was the instruction set and its encoding.  Everything followed from that.

Believe be, I appreciate every advantage high-level languages have to offer.

With this background, you'd expect I'd take to OCaml like a duck to water.

Wrong.

The language itself is actually usable.  Once you figure out how the syntax works and where to put the brackets.

But the world has changed since source code was in hexadecimal.

## Libraries

Nowdays, software rests on a huge inventory of libaries and tools.  A language, however elegant, isn't very usable for anything very practical without its libraries and their documentation.  It's not enough to know the machine inside out.

That's the hurdle I face whenever I program in OCaml -- figuring out which libraries are usable, and which are actually documented.  Not documented in the sense that someone has written an API guide and a tutorial, but documented in the sense that it is actually possible to find them.

There are often multiple packages to accomplish a single task.

You don't know which one to use.  You try the obvious one, have trouble, ask about it, and then be told, No, that one is troubled, you should use this other one instead.  The one you can download from *this* site.  So you do,  You download it.  You figure out how to edit the Makefile so that it generates the right package files.  The options you need are actually documented in the Makefile.

I had to compile my own from the original Makefile, using the options that are indeed documented inside it.XXX

I've actually manged to write a trivial 3D videogame once I was pointed to the usable OpenGL library.  The one where the function names were closely related to the ones in the OpenGL manual, of which I have a printed copy.  I didn't have to guess what functions to use.

But then you discover that the one you were recommended to use is in the opam library (the one you access by saying opam install ... with a default configuration), and you decide to simplify things by using the Opam package instead of including all the library's source code within your own project.  But when you do that, it doesn't work, because the Opam package was was configured with optons that preclude essential functionality.  (in my case, the ability to load PNG files, not just JPEG).

So what? another might say.  Just tell opam to install with different options.  But that is another *huge* problem for a beginner.

So I stick with embedding the library source code in my application.  I already understand how to edit a Makefile.

## Documentation

And try to find documentation.  I'm dealing with this problemm with gtk at the moment.  There's a lablgtk.  There's a lablgtk2.  Whats the relationship between the two?  And where's the documentation.  There's links to a tutorial all over the place, but they seem all to be to the same web page, which isn't there.

Opam has a way, I'm told, to install documentation along with the package, but  haven't been able to figure out how it works.  Or maybe, just maybe, the packages I've been trying it on don't have documentation.  Who knows?

## Are beginners even  welcome?

Is there anyone in charge of any of this?

And what's the result?  It's a lovely language, it deserves to be used, but to get something done, I find myself programming in C++ instead, even though the concpts of OCAML fit my style of programming ike a glove and fit C++ like a rusty nail keeps my hand warm.   Or spend days or months trying things, asking questions, deciphering the answers, and so forth.

I imagine if I were working in a shop where lots of people used OCaml, all the ways of doing stuff would be local folklore.  But for the isolated beginner, there's a huge barrier to entry.

It's a lovely language, but the pragmatics of its ecosystem are all wrong.  For a beginner.  For someone with experience in the particular set of tools and libraries he needs, it's great.

And most of the problem is lack of organised, findable documentation.

-- hendrik

Re: [Caml-list] Is OCaml for experienced beginners?

[Hendrik Boom]

On Thu, Dec 17, 2015 at 08:08:35PM -0500, Hendrik Boom wrote:

And in case anyone wonders, I haven't given up.  I will continue trying 
to use OCaml becuse it seems to be the right kind of tool.  Not everyone 
will be so stubborn,

-- hendrik.

> # Is anyone in charge of the OCaml ecosystem?
> 
> I am a beginner to OCaml.  I'm not a beginner to the functional style of programmins, nor to sophisticated type systems, nor to  computing in general.  I started programming in 1963, was involved with Algol 68, Lisp, and constructive type theory.  I've managed to get code running in the days when you had to enter it as numbers; the machine I  used then wouldn't even type letters other than u, v, w, x, y, z (its version of hexadecimal).  In those days what you needed to know was the instruction set and its encoding.  Everything followed from that.
> 
> Believe be, I appreciate every advantage high-level languages have to offer.
> 
> With this background, you'd expect I'd take to OCaml like a duck to water.
> 
> Wrong.
> 
> The language itself is actually usable.  Once you figure out how the syntax works and where to put the brackets.
> 
> But the world has changed since source code was in hexadecimal.
> 
> ## Libraries
> 
> Nowdays, software rests on a huge inventory of libaries and tools.  A language, however elegant, isn't very usable for anything very practical without its libraries and their documentation.  It's not enough to know the machine inside out.
> 
> That's the hurdle I face whenever I program in OCaml -- figuring out which libraries are usable, and which are actually documented.  Not documented in the sense that someone has written an API guide and a tutorial, but documented in the sense that it is actually possible to find them.
> 
> There are often multiple packages to accomplish a single task.
> 
> You don't know which one to use.  You try the obvious one, have trouble, ask about it, and then be told, No, that one is troubled, you should use this other one instead.  The one you can download from *this* site.  So you do,  You download it.  You figure out how to edit the Makefile so that it generates the right package files.  The options you need are actually documented in the Makefile.
> 
> I had to compile my own from the original Makefile, using the options that are indeed documented inside it.XXX
> 
> I've actually manged to write a trivial 3D videogame once I was pointed to the usable OpenGL library.  The one where the function names were closely related to the ones in the OpenGL manual, of which I have a printed copy.  I didn't have to guess what functions to use.
> 
> But then you discover that the one you were recommended to use is in the opam library (the one you access by saying opam install ... with a default configuration), and you decide to simplify things by using the Opam package instead of including all the library's source code within your own project.  But when you do that, it doesn't work, because the Opam package was was configured with optons that preclude essential functionality.  (in my case, the ability to load PNG files, not just JPEG).
> 
> So what? another might say.  Just tell opam to install with different options.  But that is another *huge* problem for a beginner.
> 
> So I stick with embedding the library source code in my application.  I already understand how to edit a Makefile.
> 
> ## Documentation
> 
> And try to find documentation.  I'm dealing with this problemm with gtk at the moment.  There's a lablgtk.  There's a lablgtk2.  Whats the relationship between the two?  And where's the documentation.  There's links to a tutorial all over the place, but they seem all to be to the same web page, which isn't there.
> 
> Opam has a way, I'm told, to install documentation along with the package, but  haven't been able to figure out how it works.  Or maybe, just maybe, the packages I've been trying it on don't have documentation.  Who knows?
> 
> ## Are beginners even  welcome?
> 
> Is there anyone in charge of any of this?
> 
> And what's the result?  It's a lovely language, it deserves to be used, but to get something done, I find myself programming in C++ instead, even though the concpts of OCAML fit my style of programming ike a glove and fit C++ like a rusty nail keeps my hand warm.   Or spend days or months trying things, asking questions, deciphering the answers, and so forth.
> 
> I imagine if I were working in a shop where lots of people used OCaml, all the ways of doing stuff would be local folklore.  But for the isolated beginner, there's a huge barrier to entry.
> 
> It's a lovely language, but the pragmatics of its ecosystem are all wrong.  For a beginner.  For someone with experience in the particular set of tools and libraries he needs, it's great.
> 
> And most of the problem is lack of organised, findable documentation.
> 
> -- hendrik
> 
> 
> -- 
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs

Re: [Caml-list] Is OCaml for experienced beginners?

[Gabriel Scherer]

[-- Attachment #1: Type: text/plain, Size: 7033 bytes --]

> Are beginners even welcome?

Yes, beginners are warmly welcome. Feel free to keep pointing out
changes that would help answer this question, this is helpful. Of
course small-scope changes (fixing library X to support format Y) are
always much easier to actuate than general recommendations
(more libraries).

> Is anyone in charge of the OCaml ecosystem?

No, there is no one in charge of the OCaml ecosystem, or of a general
"OCaml experience". This may explain some of the very real usability
issues, but it is also rather unclear to me how this should be
fixed. Would anyone volunteer for such a role (funded how?), and to do
what?

I agree with your conclusion that the OCaml ecosystem today is
unforgiving, and that it is particularly harsh on non-accompanied
beginners. How could this state of affairs be improved?

I think that while a unified vision for the ecosystem may be necessary
to fix some of the usability issues (one problem with unification is
that you need people to agree on it), a large part of the problem is
rather of the "death by thousand cuts" kind: small things that add up
to create an overall unpleasant experience. This portion of the
general problem is both too large for a single person to fix (no one
person can guess all use-cases), it is easily amenable to
crowd-fixing: reporting and/or fixing issues one at a time as you
discover them. So please keep doing that!


On Fri, Dec 18, 2015 at 2:13 AM, Hendrik Boom <hendrik@topoi.pooq.com>
wrote:

> On Thu, Dec 17, 2015 at 08:08:35PM -0500, Hendrik Boom wrote:
>
> And in case anyone wonders, I haven't given up.  I will continue trying
> to use OCaml becuse it seems to be the right kind of tool.  Not everyone
> will be so stubborn,
>
> -- hendrik.
>
> > # Is anyone in charge of the OCaml ecosystem?
> >
> > I am a beginner to OCaml.  I'm not a beginner to the functional style of
> programmins, nor to sophisticated type systems, nor to  computing in
> general.  I started programming in 1963, was involved with Algol 68, Lisp,
> and constructive type theory.  I've managed to get code running in the days
> when you had to enter it as numbers; the machine I  used then wouldn't even
> type letters other than u, v, w, x, y, z (its version of hexadecimal).  In
> those days what you needed to know was the instruction set and its
> encoding.  Everything followed from that.
> >
> > Believe be, I appreciate every advantage high-level languages have to
> offer.
> >
> > With this background, you'd expect I'd take to OCaml like a duck to
> water.
> >
> > Wrong.
> >
> > The language itself is actually usable.  Once you figure out how the
> syntax works and where to put the brackets.
> >
> > But the world has changed since source code was in hexadecimal.
> >
> > ## Libraries
> >
> > Nowdays, software rests on a huge inventory of libaries and tools.  A
> language, however elegant, isn't very usable for anything very practical
> without its libraries and their documentation.  It's not enough to know the
> machine inside out.
> >
> > That's the hurdle I face whenever I program in OCaml -- figuring out
> which libraries are usable, and which are actually documented.  Not
> documented in the sense that someone has written an API guide and a
> tutorial, but documented in the sense that it is actually possible to find
> them.
> >
> > There are often multiple packages to accomplish a single task.
> >
> > You don't know which one to use.  You try the obvious one, have trouble,
> ask about it, and then be told, No, that one is troubled, you should use
> this other one instead.  The one you can download from *this* site.  So you
> do,  You download it.  You figure out how to edit the Makefile so that it
> generates the right package files.  The options you need are actually
> documented in the Makefile.
> >
> > I had to compile my own from the original Makefile, using the options
> that are indeed documented inside it.XXX
> >
> > I've actually manged to write a trivial 3D videogame once I was pointed
> to the usable OpenGL library.  The one where the function names were
> closely related to the ones in the OpenGL manual, of which I have a printed
> copy.  I didn't have to guess what functions to use.
> >
> > But then you discover that the one you were recommended to use is in the
> opam library (the one you access by saying opam install ... with a default
> configuration), and you decide to simplify things by using the Opam package
> instead of including all the library's source code within your own
> project.  But when you do that, it doesn't work, because the Opam package
> was was configured with optons that preclude essential functionality.  (in
> my case, the ability to load PNG files, not just JPEG).
> >
> > So what? another might say.  Just tell opam to install with different
> options.  But that is another *huge* problem for a beginner.
> >
> > So I stick with embedding the library source code in my application.  I
> already understand how to edit a Makefile.
> >
> > ## Documentation
> >
> > And try to find documentation.  I'm dealing with this problemm with gtk
> at the moment.  There's a lablgtk.  There's a lablgtk2.  Whats the
> relationship between the two?  And where's the documentation.  There's
> links to a tutorial all over the place, but they seem all to be to the same
> web page, which isn't there.
> >
> > Opam has a way, I'm told, to install documentation along with the
> package, but  haven't been able to figure out how it works.  Or maybe, just
> maybe, the packages I've been trying it on don't have documentation.  Who
> knows?
> >
> > ## Are beginners even  welcome?
> >
> > Is there anyone in charge of any of this?
> >
> > And what's the result?  It's a lovely language, it deserves to be used,
> but to get something done, I find myself programming in C++ instead, even
> though the concpts of OCAML fit my style of programming ike a glove and fit
> C++ like a rusty nail keeps my hand warm.   Or spend days or months trying
> things, asking questions, deciphering the answers, and so forth.
> >
> > I imagine if I were working in a shop where lots of people used OCaml,
> all the ways of doing stuff would be local folklore.  But for the isolated
> beginner, there's a huge barrier to entry.
> >
> > It's a lovely language, but the pragmatics of its ecosystem are all
> wrong.  For a beginner.  For someone with experience in the particular set
> of tools and libraries he needs, it's great.
> >
> > And most of the problem is lack of organised, findable documentation.
> >
> > -- hendrik
> >
> >
> > --
> > Caml-list mailing list.  Subscription management and archives:
> > https://sympa.inria.fr/sympa/arc/caml-list
> > Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> > Bug reports: http://caml.inria.fr/bin/caml-bugs
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
>

[-- Attachment #2: Type: text/html, Size: 8499 bytes --]

Re: [Caml-list] Is OCaml for experienced beginners?

[Francois Berenger]

On 12/18/2015 03:44 PM, Gabriel Scherer wrote:
>  > Are beginners even welcome?
>
> Yes, beginners are warmly welcome. Feel free to keep pointing out
> changes that would help answer this question, this is helpful. Of
> course small-scope changes (fixing library X to support format Y) are
> always much easier to actuate than general recommendations
> (more libraries).
>
>  > Is anyone in charge of the OCaml ecosystem?
>
> No, there is no one in charge of the OCaml ecosystem, or of a general
> "OCaml experience".

I wonder if the ocaml platform mailing list

https://www.cl.cam.ac.uk/projects/ocamllabs/tasks/platform.html
http://lists.ocaml.org/listinfo/platform

isn't the closest thing to what Hendrik was looking for.

 > This may explain some of the very real usability
> issues, but it is also rather unclear to me how this should be
> fixed. Would anyone volunteer for such a role (funded how?), and to do
> what?
>
> I agree with your conclusion that the OCaml ecosystem today is
> unforgiving, and that it is particularly harsh on non-accompanied
> beginners. How could this state of affairs be improved?

I was also an isolated OCaml programmer in the past, for several years.
I remember it was discouraging sometimes and can understand some of the
associated feelings/frustration.
I however think I survived this situation pretty well, thanks to the 
many ocaml-related mailing lists (caml-list at inria, ocaml beginners at 
yahoo and the core mailing list at google groups) and the many helpful 
users on all of those lists.

There is also stack overflow (with several ocaml topics, I found) that 
works pretty well to get damn good answers on pretty much any question.

> I think that while a unified vision for the ecosystem may be necessary
> to fix some of the usability issues (one problem with unification is
> that you need people to agree on it), a large part of the problem is
> rather of the "death by thousand cuts" kind: small things that add up
> to create an overall unpleasant experience. This portion of the
> general problem is both too large for a single person to fix (no one
> person can guess all use-cases), it is easily amenable to
> crowd-fixing: reporting and/or fixing issues one at a time as you
> discover them. So please keep doing that!
>
>
> On Fri, Dec 18, 2015 at 2:13 AM, Hendrik Boom <hendrik@topoi.pooq.com
> <mailto:hendrik@topoi.pooq.com>> wrote:
>
>     On Thu, Dec 17, 2015 at 08:08:35PM -0500, Hendrik Boom wrote:
>
>     And in case anyone wonders, I haven't given up.  I will continue trying
>     to use OCaml becuse it seems to be the right kind of tool.  Not everyone
>     will be so stubborn,
>
>     -- hendrik.
>
>      > # Is anyone in charge of the OCaml ecosystem?
>      >
>      > I am a beginner to OCaml.  I'm not a beginner to the functional
>     style of programmins, nor to sophisticated type systems, nor to
>     computing in general.  I started programming in 1963, was involved
>     with Algol 68, Lisp, and constructive type theory.  I've managed to
>     get code running in the days when you had to enter it as numbers;
>     the machine I  used then wouldn't even type letters other than u, v,
>     w, x, y, z (its version of hexadecimal).  In those days what you
>     needed to know was the instruction set and its encoding.  Everything
>     followed from that.
>      >
>      > Believe be, I appreciate every advantage high-level languages
>     have to offer.
>      >
>      > With this background, you'd expect I'd take to OCaml like a duck
>     to water.
>      >
>      > Wrong.
>      >
>      > The language itself is actually usable.  Once you figure out how
>     the syntax works and where to put the brackets.
>      >
>      > But the world has changed since source code was in hexadecimal.
>      >
>      > ## Libraries
>      >
>      > Nowdays, software rests on a huge inventory of libaries and
>     tools.  A language, however elegant, isn't very usable for anything
>     very practical without its libraries and their documentation.  It's
>     not enough to know the machine inside out.
>      >
>      > That's the hurdle I face whenever I program in OCaml -- figuring
>     out which libraries are usable, and which are actually documented.
>     Not documented in the sense that someone has written an API guide
>     and a tutorial, but documented in the sense that it is actually
>     possible to find them.
>      >
>      > There are often multiple packages to accomplish a single task.
>      >
>      > You don't know which one to use.  You try the obvious one, have
>     trouble, ask about it, and then be told, No, that one is troubled,
>     you should use this other one instead.  The one you can download
>     from *this* site.  So you do,  You download it.  You figure out how
>     to edit the Makefile so that it generates the right package files.
>     The options you need are actually documented in the Makefile.
>      >
>      > I had to compile my own from the original Makefile, using the
>     options that are indeed documented inside it.XXX
>      >
>      > I've actually manged to write a trivial 3D videogame once I was
>     pointed to the usable OpenGL library.  The one where the function
>     names were closely related to the ones in the OpenGL manual, of
>     which I have a printed copy.  I didn't have to guess what functions
>     to use.
>      >
>      > But then you discover that the one you were recommended to use is
>     in the opam library (the one you access by saying opam install ...
>     with a default configuration), and you decide to simplify things by
>     using the Opam package instead of including all the library's source
>     code within your own project.  But when you do that, it doesn't
>     work, because the Opam package was was configured with optons that
>     preclude essential functionality.  (in my case, the ability to load
>     PNG files, not just JPEG).
>      >
>      > So what? another might say.  Just tell opam to install with
>     different options.  But that is another *huge* problem for a beginner.
>      >
>      > So I stick with embedding the library source code in my
>     application.  I already understand how to edit a Makefile.
>      >
>      > ## Documentation
>      >
>      > And try to find documentation.  I'm dealing with this problemm
>     with gtk at the moment.  There's a lablgtk.  There's a lablgtk2.
>     Whats the relationship between the two?  And where's the
>     documentation.  There's links to a tutorial all over the place, but
>     they seem all to be to the same web page, which isn't there.
>      >
>      > Opam has a way, I'm told, to install documentation along with the
>     package, but  haven't been able to figure out how it works.  Or
>     maybe, just maybe, the packages I've been trying it on don't have
>     documentation.  Who knows?
>      >
>      > ## Are beginners even  welcome?
>      >
>      > Is there anyone in charge of any of this?
>      >
>      > And what's the result?  It's a lovely language, it deserves to be
>     used, but to get something done, I find myself programming in C++
>     instead, even though the concpts of OCAML fit my style of
>     programming ike a glove and fit C++ like a rusty nail keeps my hand
>     warm.   Or spend days or months trying things, asking questions,
>     deciphering the answers, and so forth.
>      >
>      > I imagine if I were working in a shop where lots of people used
>     OCaml, all the ways of doing stuff would be local folklore.  But for
>     the isolated beginner, there's a huge barrier to entry.
>      >
>      > It's a lovely language, but the pragmatics of its ecosystem are
>     all wrong.  For a beginner.  For someone with experience in the
>     particular set of tools and libraries he needs, it's great.
>      >
>      > And most of the problem is lack of organised, findable documentation.
>      >
>      > -- hendrik
>      >
>      >
>      > --
>      > Caml-list mailing list.  Subscription management and archives:
>      > https://sympa.inria.fr/sympa/arc/caml-list
>      > Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
>      > Bug reports: http://caml.inria.fr/bin/caml-bugs
>
>     --
>     Caml-list mailing list.  Subscription management and archives:
>     https://sympa.inria.fr/sympa/arc/caml-list
>     Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
>     Bug reports: http://caml.inria.fr/bin/caml-bugs
>
>

-- 
Regards,
Francois.
"When in doubt, use more types"

Re: [Caml-list] Is OCaml for experienced beginners?

[Gabriel Scherer]

[-- Attachment #1: Type: text/plain, Size: 16762 bytes --]

I think that the usability of the OCaml ecosystem is very important.
I feel it is one of the highest-priority tasks for the OCaml community to
thrive, possibly the most important today. We should discuss openly what
can be done to improve the current state, and encourage people to
contribute to this improvement by highlighting moderate-cost tasks that
really do help.

There are two partly-orthogonal ways to improve the usability of the OCaml
ecosystem for beginners. One is to document it better: give more
information about each tool, give some opinionated guidance on tool
selection to reduce decision fatigue, update various parts of the online
information to make a more coherent whole where each part is informed of
the rest. The other is to improve it by improving existing projects
(evolution) or starting new ones (revolution). It is unclear to me what are
the respective usefulness, on the long term, of those various options, and
what we should encourage would-be contributors to do. It is clear than
there is not only one Right Thing to recommend, we need a bit of all of
that at the same time, and different approaches may suit better different
parts of the problem.

When I started being active in the OCaml community a few years ago (let's
say around 2008), the "pain map" was fairly different from what it is
today. We have improved considerably on many fronts, but I am afraid that
we may have largely prioritized improvements that would benefit the
existing userbase of OCaml semi-experts, at the detriment of those designed
to lower the barrier of entry. Below is a rather rambly and subjective list
of the various aspects I can think of, and how they evolved over this time
period.

+ At the time, the development of the compiler distribution felt was
perceived as a closed, opaque process. There is always room for
improvement, but I think it is fair to say that today it is evidently not
the case anymore. The compiler distribution, as a software project,
welcomes external contributions, and has a fairly active network of
external contributors. We are lucky to have such a enthusiastic crowd
hacking the compiler, and I am sometimes surprised that other important and
useful tools in the OCaml ecosystem are not similarly gifted with external
contributions.

+ Another major hurdle for OCaml users was the lack of a consensus solution
for packaging. Debian and RedHat/Fedora were (and still are, thanks to
excellent maintenance work from their OCaml package maintainers) two safe
islands were development environment were easy to setup, and GODI had a
loyal and satisfied user base, but a large part of the community still
considered external dependencies as grave sins that impeded their use of
OCaml software. ocamlfind and OPAM have brought an end to this middle-age
of OCaml library usage, and we now consider it a given that other people
than ourselves will be able to use the libraries we distribute (without
having to import their sources in the source tree). (History always moves a
little bit slower for our brave Windows OCamlers, but some unsung heroes
are doing their best there as well).

- One thing (the only thing? for non-Windows users at least) that is
currently rather bad about OPAM is its documentation. This is partly due to
the fact that it is a very flexible tool, and partly to the fact that
writing good documentation is Really Hard. This is one area where I think
everyone could contribute small improvements that would have a large
collective impact.

~ The third major blocker that I remember being clearly identified at the
time was the lack of a "extended standard library" that would cover the
everyday needs of OCaml programmers. Batteries and Core (the latter
internally inside Jane Street at first) were started around the same time
as attempts to fulfill this need, and Containers would be a notable more
recent entrant. This is a mixed success at best: we now have good "extended
libraries" which make many user's lives better, but no real "standard". It
is unclear we should keep trying to feel this role, however, given the
current use of distributing smaller, one-purpose libraries; I don't think
that the OCaml community at large currently identifies this as a blocker
high on the TODO list. On the other hand, the situation is arguably unclear
and it may be the case that beginners find this confusing.

+ Interfacing with C APIs should be easier than it previously was thanks to
the ocaml-ctypes project.

~ The library ecosystem is still poorer than we would like, with some
functional areas that are not well-covered. This can be explained by the
modest size of the community, and is improving at a steady pace.

- There is no effective standard for running the internal tests of OCaml
packages, which would be useful for quality analysis (and in particular be
of help when assessing the impact of changes to the OCaml compiler or other
parts of the base ecosystem).

-- There is no effective standard for releasing and finding the
documentation of OCaml packages. The convention of documentation comments
in .mli files (protected both by the existence of the ocamldoc tool and the
insistence on have separate interface descriptions) means that there often
*is* decent documentation for OCaml libraries, but it can still be hard for
users to find. As Hendrik Boom reports above, this disproportionately
affects beginners.

+ The Merlin project now provides solid IDE-like support for a large
portion of the OCaml community; in many ways it goes above and beyond the
state-of-the-art in terms of language-specific support for partial program
buffers. On the tooling front, ocp-indent also seems to be a success in
terms of satisfyingly solving its problem area and getting widely adopted,
but other tools (otags, ocp-index, ocamloscpe, {ocp-,ocaml}browser) seem to
have more insular usage patterns. Finally, we cannot deny that the best
OCaml programming experience is currently offered by editors from the 80s
(Emacs and Vim; notable exceptions are half-decent support for Sublime
text, and the laudable OcaIDE effort for OCaml on Eclipse that enables
teaching OCaml in some universities); this is another aspect in which
newcomers and beginners may be under-served by the current efforts targeted
at the more vocal parts of the user community.

~ Another piece of the OCaml ecosystem that expert users like to complain
about is build systems. There are many of them are none are entirely
satisfying -- exactly the right environment to get rants from expert users.
In practice, I feel they are all rather satisfying, and I wouldn't be
ashamed to see a beginner pick any of them for their project. Decision
fatigue may be part of the complaints from beginners on the ecosystem,
however.

~ Relatedly, OASIS has only a mixed standing among expert users. In
practice it has a large userbase and seem to work rather well for them. It
is currently unique in the space of "project description" systems, but it
currently does not go far enough in this direction -- in particular the
Merlin files have to be written independently, which feels like a
duplication of effort imposed on the users. I'm always a bit surprised that
Sylvain Le Gall does not receive more external contributions on this
project. This might be due to some of the technical aspects (auto-generated
files) being perceived as unwieldy.

+ We have a nice website ( http://ocaml.org/ ) that was built from the
start as a collaborative, community-driven process. (the ocaml.org
organization is not just the website and manages some very useful
infrastructure). Some parts are in need of improvement (a personal cringe
of mine is the way the spotty "tutorials" section overlaps with the
language manual and standard library documentation), but there is a clear
and easy process to improve. Do interview OCaml beginners around you about
which information they had a hard time finding, and submit pull requests to
improve it!
(On a maybe sourer note, back in 2008 we had the COCAN wiki as a very
useful community-maintained OCaml resource (not the same as the "brion
wiki" that never made it easy for external users to contribute), and it has
since fallen out of favor. Distributed good will is not quite enough to
produce high-quality online documents, and community-edited places are
harder to keep relevant than we may think.)

+ As François Berenger notes above, we do have a fairly efficient
beginner-support network in place through the caml-list and ocaml_beginners
mailing lists, the #ocaml IRC channel and the StackOverflow community. It
is a bit hard to keep track of all the cool new places (most being
proprietary walled garden because startup money trumps benevolent
sunday-afternoon contributions) people expect to get help from, but those
that I know about are well served.

+ It should also be noted that the OCaml community has remained friendly
and welcoming for as long as I know it; given the fact that no one actually
makes any effort to maintain behaviour standards, it can only be explained
by the fact that it remains small enough for people to just be nice to each
other by default.

On Fri, Dec 18, 2015 at 3:44 PM, Gabriel Scherer <gabriel.scherer@gmail.com>
wrote:

> > Are beginners even welcome?
>
> Yes, beginners are warmly welcome. Feel free to keep pointing out
> changes that would help answer this question, this is helpful. Of
> course small-scope changes (fixing library X to support format Y) are
> always much easier to actuate than general recommendations
> (more libraries).
>
> > Is anyone in charge of the OCaml ecosystem?
>
> No, there is no one in charge of the OCaml ecosystem, or of a general
> "OCaml experience". This may explain some of the very real usability
> issues, but it is also rather unclear to me how this should be
> fixed. Would anyone volunteer for such a role (funded how?), and to do
> what?
>
> I agree with your conclusion that the OCaml ecosystem today is
> unforgiving, and that it is particularly harsh on non-accompanied
> beginners. How could this state of affairs be improved?
>
> I think that while a unified vision for the ecosystem may be necessary
> to fix some of the usability issues (one problem with unification is
> that you need people to agree on it), a large part of the problem is
> rather of the "death by thousand cuts" kind: small things that add up
> to create an overall unpleasant experience. This portion of the
> general problem is both too large for a single person to fix (no one
> person can guess all use-cases), it is easily amenable to
> crowd-fixing: reporting and/or fixing issues one at a time as you
> discover them. So please keep doing that!
>
>
> On Fri, Dec 18, 2015 at 2:13 AM, Hendrik Boom <hendrik@topoi.pooq.com>
> wrote:
>
>> On Thu, Dec 17, 2015 at 08:08:35PM -0500, Hendrik Boom wrote:
>>
>> And in case anyone wonders, I haven't given up.  I will continue trying
>> to use OCaml becuse it seems to be the right kind of tool.  Not everyone
>> will be so stubborn,
>>
>> -- hendrik.
>>
>> > # Is anyone in charge of the OCaml ecosystem?
>> >
>> > I am a beginner to OCaml.  I'm not a beginner to the functional style
>> of programmins, nor to sophisticated type systems, nor to  computing in
>> general.  I started programming in 1963, was involved with Algol 68, Lisp,
>> and constructive type theory.  I've managed to get code running in the days
>> when you had to enter it as numbers; the machine I  used then wouldn't even
>> type letters other than u, v, w, x, y, z (its version of hexadecimal).  In
>> those days what you needed to know was the instruction set and its
>> encoding.  Everything followed from that.
>> >
>> > Believe be, I appreciate every advantage high-level languages have to
>> offer.
>> >
>> > With this background, you'd expect I'd take to OCaml like a duck to
>> water.
>> >
>> > Wrong.
>> >
>> > The language itself is actually usable.  Once you figure out how the
>> syntax works and where to put the brackets.
>> >
>> > But the world has changed since source code was in hexadecimal.
>> >
>> > ## Libraries
>> >
>> > Nowdays, software rests on a huge inventory of libaries and tools.  A
>> language, however elegant, isn't very usable for anything very practical
>> without its libraries and their documentation.  It's not enough to know the
>> machine inside out.
>> >
>> > That's the hurdle I face whenever I program in OCaml -- figuring out
>> which libraries are usable, and which are actually documented.  Not
>> documented in the sense that someone has written an API guide and a
>> tutorial, but documented in the sense that it is actually possible to find
>> them.
>> >
>> > There are often multiple packages to accomplish a single task.
>> >
>> > You don't know which one to use.  You try the obvious one, have
>> trouble, ask about it, and then be told, No, that one is troubled, you
>> should use this other one instead.  The one you can download from *this*
>> site.  So you do,  You download it.  You figure out how to edit the
>> Makefile so that it generates the right package files.  The options you
>> need are actually documented in the Makefile.
>> >
>> > I had to compile my own from the original Makefile, using the options
>> that are indeed documented inside it.XXX
>> >
>> > I've actually manged to write a trivial 3D videogame once I was pointed
>> to the usable OpenGL library.  The one where the function names were
>> closely related to the ones in the OpenGL manual, of which I have a printed
>> copy.  I didn't have to guess what functions to use.
>> >
>> > But then you discover that the one you were recommended to use is in
>> the opam library (the one you access by saying opam install ... with a
>> default configuration), and you decide to simplify things by using the Opam
>> package instead of including all the library's source code within your own
>> project.  But when you do that, it doesn't work, because the Opam package
>> was was configured with optons that preclude essential functionality.  (in
>> my case, the ability to load PNG files, not just JPEG).
>> >
>> > So what? another might say.  Just tell opam to install with different
>> options.  But that is another *huge* problem for a beginner.
>> >
>> > So I stick with embedding the library source code in my application.  I
>> already understand how to edit a Makefile.
>> >
>> > ## Documentation
>> >
>> > And try to find documentation.  I'm dealing with this problemm with gtk
>> at the moment.  There's a lablgtk.  There's a lablgtk2.  Whats the
>> relationship between the two?  And where's the documentation.  There's
>> links to a tutorial all over the place, but they seem all to be to the same
>> web page, which isn't there.
>> >
>> > Opam has a way, I'm told, to install documentation along with the
>> package, but  haven't been able to figure out how it works.  Or maybe, just
>> maybe, the packages I've been trying it on don't have documentation.  Who
>> knows?
>> >
>> > ## Are beginners even  welcome?
>> >
>> > Is there anyone in charge of any of this?
>> >
>> > And what's the result?  It's a lovely language, it deserves to be used,
>> but to get something done, I find myself programming in C++ instead, even
>> though the concpts of OCAML fit my style of programming ike a glove and fit
>> C++ like a rusty nail keeps my hand warm.   Or spend days or months trying
>> things, asking questions, deciphering the answers, and so forth.
>> >
>> > I imagine if I were working in a shop where lots of people used OCaml,
>> all the ways of doing stuff would be local folklore.  But for the isolated
>> beginner, there's a huge barrier to entry.
>> >
>> > It's a lovely language, but the pragmatics of its ecosystem are all
>> wrong.  For a beginner.  For someone with experience in the particular set
>> of tools and libraries he needs, it's great.
>> >
>> > And most of the problem is lack of organised, findable documentation.
>> >
>> > -- hendrik
>> >
>> >
>> > --
>> > Caml-list mailing list.  Subscription management and archives:
>> > https://sympa.inria.fr/sympa/arc/caml-list
>> > Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
>> > Bug reports: http://caml.inria.fr/bin/caml-bugs
>>
>> --
>> Caml-list mailing list.  Subscription management and archives:
>> https://sympa.inria.fr/sympa/arc/caml-list
>> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
>> Bug reports: http://caml.inria.fr/bin/caml-bugs
>>
>
>

[-- Attachment #2: Type: text/html, Size: 18405 bytes --]