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

[Viktor Dukhovni]

On Fri, Sep 17, 2021 at 11:27:12AM +0900, Michael Turner wrote:

> > I am also curious whether I'm part of the solution or part of the
> > precipitate.  I've recently contributed new documentation for
> > Data.Foldable and Data.Traversable:
> >
> >     https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Foldable.html#g:7
> >     https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Traversable.html#g:4
> 
> OK:
> 
> "Merging the contribution of the current element with an accumulator
> value from a partial result is performed by an operator function,
> either explicitly provided by the caller as in foldr, implicit count
> as in length, or partly implicit as in foldMap (where each element is
> mapped into a Monoid, and the monoid's mappend operator performs the
> merge)."
> 
> Let me tell you how I tried to read that lo-o-ong sentence.

If I may trouble you just a bit longer, I'd like to ask whether the
problem is the phrasing, or the selection of subject matter.  If the
latter, then any defects in the phrasing are perhaps moot.

Supposing I rephrase the same thing as:

   The contribution of each element to the final result is combined with an
   accumulator via an /operator/ function.  The operator may be explicitly
   provided by the caller as in `foldr` or may be implicit as in `length`. In
   the case of `foldMap`, the caller provides a function mapping each element
   into a suitable 'Monoid', which makes it possible to merge the per-element
   contributions via that monoid's `mappend` function.

Does that help?  At all?  Enough?  The word "Monoid" hyperlinks to the
documentation of that class, and I thought it fair to reference Monoids
in the reference documentation for a module that defines `foldMap`.

If the above is helpful, I am not too proud to rewrite any paragraphs
that are poorly phrased, if there is some merit in the subject matter.

I don't think the module overview can be a beginner tutorial, that's
more the domain of books, ...  I think that the descriptive prose in the reference
docs that follows the function synopses just need to cover any concepts
and API behaviours that don't immediately follow from those synopses.

A rough guide for me were Unix manpages, where e.g. setsockopt(2) is not
a networking tutorial, and yet still has a bunch of useful prose, and not
just function signatures.

-- 
    Viktor.