[Haskell-cafe] Comments from OCaml Hacker Brian Hurt

[Andrew Coppin]

Sebastian Sylvan wrote:
>
>
> On Thu, Jan 15, 2009 at 7:46 PM, Andrew Coppin 
> <andrewcoppin at btinternet.com <mailto:andrewcoppin at btinternet.com>> wrote:
>
>     The sad thing is, it's not actually complicated. The documentation
>     just makes it seem like it is! :-(
>
>
> This is so true for a heck of a lot of things. Existential 
> quantification being just one of them. Loads of things in Haskell have 
> big powerful (but scary) names which I really think intimidate people, 
> the situation isn't helped when a lot of tutorials use the theoretical 
> basis for the construct as a starting point, rather then actually 
> describing the construct from the perspective of a programmer first 
> (see Monads).
> Haskell really isn't that difficult compared to other languages, but 
> people still get the impression that you need to be a big brain on a 
> stick to use it, terminology is certainly part of the equation.
>
> This doesn't mean that making up new words is always better, but we 
> should certainly strive to exploit any opportunity to clarify the 
> issue and (this means that haddock comments and language 
> books/tutorials shouldn't refer to academic papers first and foremost, 
> but use common English and practical examples to describe what's being 
> used, and academic nerds can consult the footnotes for their fill of 
> papers containing pages of squiggly symbols!).

I basically agree with most of what you just said.

I'm not sure having a Monoid class is actually useful for anything - but 
if we must have it, there seems to be little better possible name for 
something so vague.

{-# LANGUAGE ExistentialQuantification #-} is an absurd name and should 
be changed to something that, at a minimum, tells you it's something to 
do with the type system. (Ideally it would also be pronouncible.) Of 
course, nobody will take any notice, since changing this would induce 
mass breakage for all the millions of LoC that already use the old name.

I think "documenting" a package by saying "read this academic paper" 
should be banned. (Most especially if the paper in question isn't even 
available online and can only be obtained from a reputable university 
library!!) For example, I was looking at one of the monad transformers 
(I don't even remember which one now), and the Haddoc contained some 
type signatures and a line saying "read this paper". The paper in 
question mentioned the transformer in passing as a 5-line example of how 
to use polymorphism, but *still* without explaining how to actually use 
it! (I.e., the paper was about polymorphism, and this transformer was 
just a quick example.) What the hell??

I presume I can call "more documentation please!" without upsetting even 
the most ardant category theory millitant... ;-)

Unfortunately, it's not going to write itself, and I have no idea how to 
solve the problem. (That is, even if I wrote some better documentation 
myself, I don't know how to submit it to get it into the official 
package documentation. E.g., Parsec has a great tutorial document, but 
the Haddoc pages are barren. It'd be easy to fix, but I don't know how 
to submit the updates.)