[Haskell-cafe] Comments from OCaml Hacker Brian Hurt

[Lennart Augustsson]

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-haskell at 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.dubuisson at gmail.com> wrote:
>>>
>>> On Thu, Jan 15, 2009 at 4:12 PM, Sittampalam, Ganesh
>>> <ganesh.sittampalam at 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 at haskell.org
>> http://www.haskell.org/mailman/listinfo/haskell-cafe
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>