[Haskell-cafe] Best to not go there...

[Viktor Dukhovni]

On Sat, Sep 18, 2021 at 03:35:29PM +1200, Anthony Clayden wrote:

> In fact it's deliberate that the docos are exclusionary. As part of
> this grand plan, Viktor is deliberately making the Libraries docos
> impenetrable. (By which I mean: the style is clear, but the material
> is unlearnable. Apparently I need to know what is an endomorphism
> before I can write a Foldable instance)

I believe I'm owed an apology.  The above is inappropriate snark that
does not belong on this forum.  If we start finger pointing at people
driving away participation, perhaps a look in the mirror is warranted.

It's not like I took a bunch of extant accessible background material
and made it harder to read.  There was none there to be found.

So my excuse could be that in the worst case if it is doing nothing for
you, then just stop reading it and you're no worse off.

However, I am not planning to hide behind that.  Yes, I slipped up and
labeled those particular `b -> b` terms "endomorphisms" without
explaining or motivating the use of the term.

I should probably have left the term out, or else justified its use
(deeper down the rabbit hole, so I doubt you'd go there) by observing
that we're transforming the original fold into a fold of function terms
under composition, which of course requires these to have the same input
and output types, i.e. be "endomorphisms".  This is probably how a tiny
fragment of that thought process slipped into the final text.

Mea culpa, but it is then rather a leap to say "Viktor is deliberately
making the Libraries docos impenetrable".

I might note that the concept of endomorphisms already appeared in the
"Laws" section of the GHC 7.10 documentation (unsabotaged by me) in the
form of unexplained "Endo" and "appEndo" terms:

    https://hackage.haskell.org/package/base-4.8.0.0/docs/Data-Foldable.html

    Foldable instances are expected to satisfy the following laws:

        foldr f z t = appEndo (foldMap (Endo . f) t ) z
        foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
        ...

I did (with recent moral support it seems) move the laws section to the
end of the docs, precisely because I thought many a reader would find
the section more puzzling than helpful.

Though I likely slipped up more than once by using some avoidable
jargon, this seems a rather thin justification for condemning the entire
effort as deliberate obfuscation.  The goal of the writeup is to cover
topics to which mere synopses don't do enough justice.  Somewhat
advanced material is properly in scope.  No writeup will cater to all
audiences, sorry it did not work out for you.

-- 
    Viktor.

P.S. I'll elide "endomorphism" for the next update.

If you'd like to write some text from a more approachable perspective
that augments or replaces the current text, by all means open an MR in
gitlab, and if it does a better job, I'll be among those cheering for it
to be merged.