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

Sebastian Sylvan wrote:

On Thu, Jan 15, 2009 at 7:46 PM, Andrew Coppin mailto:andrewcoppin@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.)