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

[Dominik Schrempf]

I really enjoyed reading through the documentation Viktor has contributed, thank
you! No doubt, as Michael writes, things can be improved, but in my opinion it
is much better than before.

Actually, I was astonished to see such a nice overview on Hackage! And this
directly relates to the core of the problem Michael is addressing: I am used to
having "adequate" documentation on Hackage, and these paragraphs stood out.

Viktor Dukhovni <ietf-dane at dukhovni.org> writes:

> 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?