By no means do I suggest that Wikipedia should replace Haskell library documentation. I think the libraries should be documented in a mostly stand-alone way (i.e., no references to old papers etc.). In the case of Monoid, a few lines of text is enough to convey the meaning of it and gives an example.
-- Lennart On Thu, Jan 15, 2009 at 4:46 PM, Ross Mellgren <rmm-hask...@z.odi.ac> wrote: > For what it's worth, many (most/all?) programmers I know in person don't > have the slightest clue about Category Theory and they may have known about > abstract algebra once upon a time but certainly don't remember any of it > now. They usually understand the concepts perfectly well enough but by "lay > terms" or by no particular name at all. > > Personally, I don't mind it too much if the generic typeclasses are named > using extremely accurate terms like Monoid, but saying that someone should > then look up the abstract math concept and try to map this to something very > concrete and simple such as a string seems like wasted effort. > > Usually when encountering something like "Monoid" (if I didn't already know > it), I'd look it up in the library docs. The problem I've had with this > tactic is twofold: > > First, the docs for the typeclass usually don't give any practical examples, > so sometimes it's hard to be sure that the "append" in "mappend" means what > you think it means. > > Second is that there appears to be no way to document an _instance_. It > would be really handy if there were even a single line under "Instances > > Monoid ([] a)" that explained how the type class was implemented for the > list type. As it is, if you know what a Monoid is already, it's easy to > figure out how it would be implemented. If you don't, you're either stuck > reading a bunch of pages on the generic math term monoid and then finally > realizing that it means "appendable" (and other similar things), or > grovelling through the library source code seeing how the instance is > implemented. > > My 2 cents, > > -Ross > > > On Jan 15, 2009, at 11:36 AM, Lennart Augustsson wrote: > >> Most people don't understand pure functional programming either. Does >> that mean we should introduce unrestricted side effects in Haskell? >> >> -- Lennart >> >> On Thu, Jan 15, 2009 at 4:22 PM, Thomas DuBuisson >> <thomas.dubuis...@gmail.com> wrote: >>> >>> On Thu, Jan 15, 2009 at 4:12 PM, Sittampalam, Ganesh >>> <ganesh.sittampa...@credit-suisse.com> wrote: >>>> >>>> Lennart Augustsson wrote: >>>>> >>>>> I have replied on his blog, but I'll repeat the gist of it here. >>>>> Why is there a fear of using existing terminology that is exact? >>>>> Why do people want to invent new words when there are already >>>>> existing ones with the exact meaning that you want? If I see Monoid I >>>>> know what it is, if I didn't know I could just look on Wikipedia. >>>>> If I see Appendable I can guess what it might be, but exactly what >>>>> does it mean? >>>> >>>> I would suggest that having to look things up slows people down >>>> and might distract them from learning other, perhaps more useful, >>>> things about the language. >>> >>> Exactly. For example, the entry for monoid on Wikipedia starts: >>> "In abstract algebra, a branch of mathematics, a monoid is an >>> algebraic structure with a single, associative binary operation and an >>> identity element." >>> >>> I've had some set theory, but most programmers I know have not. >>> >> _______________________________________________ >> Haskell-Cafe mailing list >> Haskell-Cafe@haskell.org >> http://www.haskell.org/mailman/listinfo/haskell-cafe > > _______________________________________________ > Haskell-Cafe mailing list > Haskell-Cafe@haskell.org > http://www.haskell.org/mailman/listinfo/haskell-cafe > _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
