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

[Viktor Dukhovni]

On Wed, Sep 15, 2021 at 04:07:38PM +0900, Michael Turner wrote:

> The real problem is that the writing sucks. Not all of it -- and some
> contributors to the community are stellar writers, even if, in the
> snarkish commentary they write about Haskell and the community, I
> don't quite get all the jokes. But speaking as a contributor to the
> Haskell.org wiki -- to which I contribute at times out of hope that
> clarifying points I understand will also lead to more clarity for
> myself -- I have to say it: the writing sucks.

Can you be a bit more specific about which sort of writing you find
sufficiently unsatisfactory to say "the writing sucks"?

    * Books about Haskell
      - Introductory (e.g. http://learnyouahaskell.com/)
      - Comprehensive (e.g. the classic Real World Haskell)
      - Topic focused (e.g. the IMHO rather excellent Parallel and
        Concurrent Haskell)
      - Theory focused (e.g.
        https://bartoszmilewski.com/category/category-theory/)
      - ...
    * The library reference documentation?
    * The GHC User's Guide?
    * The Haskell report?
    * Blog posts?
    * The Haskell Wiki?
    * r/haskell?
    * Haskell mailing lists?
    ...
    * All of the above???

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

are these a step in the right direction, or examples of more writing
that sucks?  These are reference documentation, not beginner tutorials,
so a more detailed write up of the concepts, pitfalls, ... things to
keep in mind when using library, ...

More of that sort of thing would help me to more quickly learn to use
some of the libraries that lack this sort of overview prose, but perhaps
what you're looking for is something else?

-- 
    Viktor.