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

[John Lato]

> From: Derek Elkins <derek.a.elkins at gmail.com>
>
> On Sun, Oct 11, 2009 at 8:55 AM, Iain Barnett <iainspeed at gmail.com> 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).