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.)