2¢ from a Haskell newbie, who would be delighted to be instructed or corrected:
I have experienced some of the same issues mentioned earlier in this thread when trying to read code written by a real expert (e.g. from "How do I verbalize that, to think out loud or discuss it with someone else?" to "Why that particular abstraction at this point?"). I tend to think that Haskell has no exclusive claim on this consideration. Witness, for example, the experience of a newcomer looking at a compact Java source file that makes heavy use of generics and framework-specific annotations. However, as one of the most directly mathematically-influenced programming languages, I can also believe that it may happen to a greater degree in Haskell than most others.
Mathematics, Haskell, and certain approaches to programming tend to share the practice of building up an elegant pyramid of abstraction which allows one to say more and more with fewer and fewer marks. (Witness the description of Maxwell's laws at
https://en.wikipedia.org/wiki/Maxwell%27s_equations .)
I suspect that a beginner to any of the above, on first examining an artifact from an expert practitioner, will struggle to find the keyhole (or even the doorknob). As a part time instructor, I also struggle with the degree to which some "explanations" risk either dumbing-down important concepts or covering them in so much metaphorical baggage that they actually exacerbate the problem faced by the student.
Just as agile practitioners use spikes to explore the skeleton of a problem, knowing full well that they have simplified it for the purpose of addressing one concern, I'm starting to experiment with "spike explanations" that draw a simplified connection from the apex of the pyramid to ground level. For example:
For present purposes, think of a monoid as a general scheme for accumulating a result over a specific data type, such as the sum of integers or the concatentation of strings. We'll talk later about some specific expectations that must be satisfied.
An expert is going to say (or write) high-economy utterances that other experts will instantly grasp and that newcomers will find opaque. I suspect that the editing process that the original poster described is the crucial part of developing an understanding. One "spike explanation" technique with which I have had some success involves starting with a verbose, concrete artifact (e.g. bit of source code), then progressively editing re-factoring it into the final nicely-abstracted, economical form. Accessible examples that come to mind include
http://blog.sigfpe.com/2006/08/you-could-have-invented-monads-and.html and
http://codon.com/refactoring-ruby-with-monads .
I'd be very interested to know whether there examples of this technique for more advanced Haskell code.
Thanks,
Joel