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

2009/3/27 Achim Schneider :

wren ng thornton wrote:

...

Colin Adams wrote:

...

2009/3/25 wren ng thornton : 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).