On Thu, 2009-01-15 at 21:17 +0000, Andrew Coppin wrote: > Sebastian Sylvan wrote: > > > > > > On Thu, Jan 15, 2009 at 7:46 PM, Andrew Coppin > > <andrewcop...@btinternet.com <mailto:andrewcop...@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... ;-)
But you don't seem to be capable of separating your valid complaints from your invalid ones. Everyone wants the Haddock documentation to be maximally useful. But the should never be a confusion between *defining* a term used in a library and *choosing* that term. They are simply different activities, and neither can be a substitute for the other. jcc _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
