Colin Adams <colinpaulad...@googlemail.com> wrote: > 2009/3/27 Achim Schneider <bars...@web.de>: > > wren ng thornton <w...@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. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe