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

[Achim Schneider]

Colin Adams <colinpauladams at googlemail.com> wrote:

> 2009/3/27 Achim Schneider <barsoap at web.de>:
> > wren ng thornton <wren at freegeek.org> wrote:
> >
> >> Colin Adams wrote:
> >> > 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).
> 
Shoot err... rewrite before asking. If in doubt, annihilate.
Considering all options, just do it. Pity is a thing for judges, not
hackers. Something along those lines.

> >
> > 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).
>
Hm. Yes. OTOH, I very much appreciate background information, it
usually contains very insightful information about the overall idea and
behaviour of a library. I'm by no means a domain expert for any
and every library I want to use.

In school, we were required to write both user[1] as well as
developer[2] documentation alongside to commenting our code. I tended
to loathe it, but it's very, very sensible in retrospect.

There was some discussion a while back here on the cafe about enabling
users to write additional documentation into a wikised hackage;
together with an #haskell-doc-tutor irc channel, we could have an
excellent solution to both lacking documentation as well as newbies
not being sure were to start and/or intimidated by pointless usage of
(.). Additionally, you get the chance of earning credits and naming and
shaming Haskell's godfathers[1].


[1] In the sense of using the code, either as app or library
[2] In the sense of editing/reading the code. Understanding [2] usually
    involves understanding [1].
[3] Judging from his code, I guess dons' apartment looks just like
    mine: Lots of left-over bits lying around that you tend to stumble
    over and are unsure about why they are still there. I swear, someday
    I'm going to use those two 5 1/4" floppy drives...

-- 
(c) this sig last receiving data processing entity. Inspect headers
for copyright history. All rights reserved. Copying, hiring, renting,
performance and/or quoting of this signature prohibited.