I like to tell people that all learning is pain. It’s a sort of contrarianism that I picked up from Buddhism, I guess, where the first noble truth is that everything is pain.

A more careful restatement: we learn abstractions to organize experience, and we learn them only to the extent that they relieve a painful messiness in our experience. So the failure of the Haskell monad tutorial, to take one particular instance, is the failure of “look this was so hard for me that I must make it easy for others.” Let’s give pain relief before the problem sets in. Only problem is, “no pain no gain”: you needed to experience that messiness and confusion before your brain could find a way to understand the underlying principles and organize it. So someone reads your tutorial and has even less of a clear idea because they now pretend to an abstract knowledge which they do not have any concrete experiences to tie it to.

Caveat: this is how my brain works but I cannot be sure about others’.

You can discourage this by writing code that doesn't just perform the required task, but also makes its theory clear to the reader.