* Andrew Coppin
A problem I see a lot of [and other people have mentioned this] is that a lot of documentation presents highly abstracted things, and gives *no hint* of why on earth these might possibly be useful for something.
I think this is definitely something that should be addressed by better documentation of some kind. Unfortunately, this is quite possibly the hardest kind of knowledge to put down into words: before you learn the concepts, you don't know them, so you can't write about them, but after you learn them, they seem so obvious that you don't know how to describe them. (At least, this is typically the problem I have; I can answer questions about something easily, maybe even walk someone through understanding it, but I can't draft a document that will describe things adequately to a newbie). This problem is worse in Haskell than other languages, simply because abstractions are used more frequently and pervasively in Haskell. In many other languages, these abstractions are perfectly applicable, but actually encoding them in the language is simply too unwieldy. Thus, while the abstraction may be present as a fuzzy concept at the back of the programmer's mind, or even as a "design pattern", the code people actually work with tends to be at a more concrete level, despite the more limited possibilities of code reuse at this level. This ties in with the complaint that Haskell variable / parameter names aren't descriptive enough. You frequently hear things like "why call it 'xs' instead of 'applicableItems'?"; often, the answer to this is simply that the value in question is something so general that you cannot describe it more specifically than "a list of something or other". Haskell code is being written at a higher level of abstraction than the newcomer is used to, and thus the highly abstract names are mistaken for vague or imprecise names. Now, it's all very well to explain the reasons behind this to the newcomer, but they're still left in a position where they can't find the tools they need to solve a particular problem. They're used to looking for the concrete tools they need to do some task or another, which aren't there; instead, there are all these abstract tools which can perform the concrete task at hand, but what is really needed is help finding the abstract tool for the concrete task at hand, or even abstracting the concrete task at hand, thus making the choice of abstract tool(s) an obvious one. Sure, you can pop into #haskell and hopefully find someone to walk you through the processes until you begin to understand the abstractions yourself, but I think we (I almost hesitate to include myself, given my own relatively miniscule Haskell knowledge) can do better than this in terms of helping people unfamiliar with these concepts. Also, more importantly, I'm referring specifically to teaching *programmers* the concepts; I have no problem with *naming* things based on category theory or abstract algebra or quantum mechanics, but I should not be required to learn half a dozen fields of mathematics or physics in order to *use* things. Writing about how Monads in Haskell relate to Monads in category theory is of interest to category theorists, but isn't something programmers should be reading. Hopefully nothing I've said here comes as a surprise to anyone, and I'd be surprised if there were many serious objections to any of it, but perhaps it does need to be highlighted more prominently as an important area to improve if Haskell is to grow as a programming language. -- mithrandi, i Ainil en-Balandor, a faer Ambar