[Haskell-cafe] Re: Comments from OCaml Hacker Brian Hurt

[John Lato]

Manlio Perillo wrote:
>
> I'm fine with current names.
>
> However I would like to see better documentation, and examples.
>
> You can't just have in the documentation:
> this is xxx from yyy branch of mathematics, see this paper.
>
> You should explain how (and why) to use xxx.
>

Absolutely this!  I would rather have to look up Monoid than see
Appendable used for operations that don't fit my notion of appending.
I don't care much what things are called as long as it's accurate.
Even so, I typically find Haskell's documentation to be not very
helpful, because it's aimed towards category theorists.  That is,
Haskell documentation often seems to take the approach "The reader is
familiar with [branch of abstract mathematics], so knows all these
concepts.  The job of the documentation is to show how standard
terminology from [branch of abstract math] is written in Haskell".

The problem with this is that most people aren't familiar with general
abstract nonsense, and this documentation is useless for those, i.e.
most, people.  In fact, most people don't care about how abstract
nonsense is written in Haskell.  They care about solving their
particular problems, and are only interested in abstract nonsense to
the sense that it can be useful in solving those problems.
Overwhelmingly the documentation does not show how particular concepts
apply to actual programming problems, or any concrete problems at all.

Here is the current complete documentation for Data.Monoid 'mappend',
which happens to be a good example of which I speak:

    An associative operation

That could mean anything.  There are lots of associative operations.
Should I believe the name that somehow this operation is append-like?
If so, and I'm using a list instance, where are items appended to?  Is
it an append onto the tail of the list, or is it really a cons?  I
would expect the documentation to cover this, but it doesn't.  Far too
often the documentation fails to provide this sort of useful,
practical information.

This is the problem faced by an abstract-nonsense unaware user:  I
want to accomplish [some task].  Some blogger wrote that [monoids,
functors, arrows, etc.] provide a good solution.  But when I look up
[monoids, functors, etc.] in [some academic paper], it doesn't show
how these concepts apply to the problem at hand, or indeed any
programming problem at all.  In fact, I can't even understand what the
doc says without first learning about [even more abstract stuff].  So
now the user needs to develop a strong background in [some abstract
topic] he/she doesn't care about just to figure out *if* that abstract
topic could possibly be useful.  At this point most users will give
up.  If instead they had access to documentation that says "[Monoids]
are useful programming abstractions because they can solve problems A,
B, and C in these manners, and incidentally they can do all this other
stuff too", the same users would not only stick with Haskell longer,
they would increase their theoretical awareness at the same time.  I
think even the most elitist Haskell users would think this is a good
outcome.

Of course this better documentation would need to be written.
Somebody upthread (Duncan?) suggested that suitable individuals may
not exist, and I agree with that.  Of people who understand the
material well enough to document it, many are busy doing other work,
and many have no interest or are ideologically opposed to writing
documentation of this type.

This situation reminds me very much of a particularly well-known
article by Milton Babbitt, "Who Cares If You Listen."  I expect that
many Haskellers would find it interesting at the least.

John Lato