<div dir="auto">I am not a fan of how the new Traversable documentation buries the actual laws.</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Sep 16, 2021, 4:55 PM Viktor Dukhovni <<a href="mailto:ietf-dane@dukhovni.org">ietf-dane@dukhovni.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Wed, Sep 15, 2021 at 04:07:38PM +0900, Michael Turner wrote:<br>
<br>
> The real problem is that the writing sucks. Not all of it -- and some<br>
> contributors to the community are stellar writers, even if, in the<br>
> snarkish commentary they write about Haskell and the community, I<br>
> don't quite get all the jokes. But speaking as a contributor to the<br>
> Haskell.org wiki -- to which I contribute at times out of hope that<br>
> clarifying points I understand will also lead to more clarity for<br>
> myself -- I have to say it: the writing sucks.<br>
<br>
Can you be a bit more specific about which sort of writing you find<br>
sufficiently unsatisfactory to say "the writing sucks"?<br>
<br>
    * Books about Haskell<br>
      - Introductory (e.g. <a href="http://learnyouahaskell.com/" rel="noreferrer noreferrer" target="_blank">http://learnyouahaskell.com/</a>)<br>
      - Comprehensive (e.g. the classic Real World Haskell)<br>
      - Topic focused (e.g. the IMHO rather excellent Parallel and<br>
        Concurrent Haskell)<br>
      - Theory focused (e.g.<br>
        <a href="https://bartoszmilewski.com/category/category-theory/" rel="noreferrer noreferrer" target="_blank">https://bartoszmilewski.com/category/category-theory/</a>)<br>
      - ...<br>
    * The library reference documentation?<br>
    * The GHC User's Guide?<br>
    * The Haskell report?<br>
    * Blog posts?<br>
    * The Haskell Wiki?<br>
    * r/haskell?<br>
    * Haskell mailing lists?<br>
    ...<br>
    * All of the above???<br>
<br>
I am also curious whether I'm part of the solution or part of the<br>
precipitate.  I've recently contributed new documentation for<br>
Data.Foldable and Data.Traversable:<br>
<br>
    <a href="https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Foldable.html#g:7" rel="noreferrer noreferrer" target="_blank">https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Foldable.html#g:7</a><br>
    <a href="https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Traversable.html#g:4" rel="noreferrer noreferrer" target="_blank">https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Traversable.html#g:4</a><br>
<br>
are these a step in the right direction, or examples of more writing<br>
that sucks?  These are reference documentation, not beginner tutorials,<br>
so a more detailed write up of the concepts, pitfalls, ... things to<br>
keep in mind when using library, ...<br>
<br>
More of that sort of thing would help me to more quickly learn to use<br>
some of the libraries that lack this sort of overview prose, but perhaps<br>
what you're looking for is something else?<br>
<br>
-- <br>
    Viktor.<br>
_______________________________________________<br>
Haskell-Cafe mailing list<br>
To (un)subscribe, modify options or view archives go to:<br>
<a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe" rel="noreferrer noreferrer" target="_blank">http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe</a><br>
Only members subscribed via the mailman list are allowed to post.</blockquote></div>