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

[David Feuer]

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

On Thu, Sep 16, 2021, 4:55 PM Viktor Dukhovni <ietf-dane at dukhovni.org>
wrote:

> 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.
> _______________________________________________
> Haskell-Cafe mailing list
> To (un)subscribe, modify options or view archives go to:
> http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
> Only members subscribed via the mailman list are allowed to post.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20210916/169d5cc4/attachment.html>