[Haskell-cafe] Re: about Haskell code written to be "too smart"

[Colin Adams]

2009/3/27 Achim Schneider <barsoap at web.de>:
> wren ng thornton <wren at freegeek.org> wrote:
>
>> Colin Adams wrote:
>> > 2009/3/25 wren ng thornton <wren at freegeek.org>:
>> > when I look up the Haddock-generated documentation for a function, I
>> > DON'T appreciate it if that is in the form of a hyperlink to a
>> > research paper.
>> > And that occurs in several of the libraries shipped with GHC for
>> > instance.
>> >
>> > A reference to a research paper is fine to show where the ideas came
>> > from, but that is not where the library documentation should be.
>>
>> Yeah, that's bad. 'Documentation' like that should be corrected with
>> Extreme Prejudice.

I think I agree with that (I say I think, as I'm not sure what Extreme
Prejuidice means).

>>
> The main problem with research papers as documentation is the papers
> usually being outdated wrt. the current library version: Literate
> Haskell is utterly underused.
>

That's surely a problem, and a significant one.

But what irks me is the time taken to find one small piece of
information (how to use a single function).
I would guess on average about the time to read 1/3 of the paper
(since the back matter needn't be examined).