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