[Haskell-cafe] Haskell's "historical futurism" needs better writing, not better tools

[Viktor Dukhovni]

On Thu, Sep 16, 2021 at 04:57:28PM -0400, David Feuer wrote:

> I am not a fan of how the new Traversable documentation buries the
> actual laws.

The laws are one click away from the table of contents, and IMHO not
particularly illuminating other than for advanced readers.

For example, in Data.Foldable they are:

    foldr f z t = appEndo (foldMap (Endo . f) t ) z
    foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
    fold = foldMap id
    length = getSum . foldMap (Sum . const 1)

is someone new to Data.Foldable really going to learn something from
these before they've deeply understood the background concepts?

My take is that the laws should almost always be "buried" (one click
away) at the end of the module documentation.  Those who care and need
them can find them, but I think they just intimidate the less
experienced readers.  Putting the laws first likely only discourages
beginners.

-- 
    Viktor.