[Haskell-cafe] Documentation (was: ANN: text 0.5, a major revision of the Unicode text library)

[John Lato]

For anyone writing introductions to generic programming, take this as
a plea from Haskellers everywhere.  If one of the RWH authors can't
understand how to make use of these techniques, what hope do the rest
of us have?

John Lato

P.S. Some might wryly note that I'm the maintainer of a package which
is also known for incomprehensible documentation.  To which I would
reply that our effort is much newer, I consider it a problem, and it's
being worked on, contrasted to the state of GP where similarly
impenetrable documentation has been and continues to be the norm.

>
> From: "Bryan O'Sullivan" <bos at serpentine.com>
>
> I think maybe someone else will have to take a crack at a Data instance for
> Text, because the documentation for Data.Data is not written in English. In
> its syntax and structure, it closely hews to what we think of as English,
> but it is the kind of documentation that can only be understood by someone
> who already knows what it is going to say.
>
> This is an exemplar of my experience with the cottage industry of generic
> programming in Haskell: I'd really quite like to use the stuff, but for
> goodness's sake, o beloved researchers, please aim your expository papers at
> non-specialists once in a while. An endless chain of papers of the form "my
> technique, which you won't understand, is better than this other technique,
> which you haven't read about and won't anyway understand, in subtle ways
> that you won't understand" does not feel to me like progress.
>
> Yours in some misery and frustration,
> Bryan.