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.