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

From: Derek Elkins

On Sun, Oct 11, 2009 at 8:55 AM, Iain Barnett wrote:

...

On 11 Oct 2009, at 13:58, John Lato wrote:

...

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.

You could say that about most documentation (for Haskell and beyond). Apparently, programmers like programming better than documenting. The effect of this is that less people use their programming, making their efforts redundant.

Silly really, considering programmers are (allegedly:) intelligent.

Apparently, programmers like programming better than reading as well... in my experience.

I won't disagree. But I think the real difficulty is that the intersection of programmers who can come up with really good ways to solve problems (not even all programmers, unfortunately) and people who are good at writing documentation is vanishingly small. It seems to me that when someone works in a problem domain (e.g. Generic Programming), they gain a very deep understanding of that area and are used to working at a certain level within it. When introducing the topic to newcomers (even ostensibly smart programmers) the introduction can't assume prior knowledge of the problem domain, but the authors are so used to thinking at one level they often take for granted knowledge that the audience doesn't have. I don't think this problem is particular to programming, but it is common in Haskell. Most likely because Haskell, with a reputation as a research language, has a lot of computer science types doing research in wide-ranging topics. Somebody's expertise in category theory, for example, might not directly carry over to generic programming (or maybe it does; I'm not an expert in either).