[Haskell-cafe] Haskell reference documentation, laws first or laws last?

[Viktor Dukhovni]

On Thu, Sep 16, 2021 at 09:56:37PM -0400, Viktor Dukhovni wrote:

> Surely a one click link from the Prelude re-export is no worse than a 1-click link
> in the module table of contents?
> 
> I am rather reluctant beat new readers over the head with laws that often are much
> too abstract to add clarity.

I've opened an MR: https://gitlab.haskell.org/ghc/ghc/-/merge_requests/6555

that adds a "Laws" link to the class head haddocks, and attempts to
improve some prose that was found a bit wanting in the recent threads.

    https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Prelude.html#g:11

    https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Foldable.html#overview

The Overview of Data.Foldable is aimed at a novice to intermediate
Haskell programmer, not a complete beginner or someone long familiar
with the ins and outs of folds.  The idea is to help the reader be able
to reason about the various Foldable methods and choose the right one
for the task at hand.  Maybe, though not the main intent, to write better
Foldable instances (if not simply derived).

Perhaps the intended audience should be explicitly stated, to save
complete beginners who are not ready for it, or seasoned Haskellers who
don't need it the trouble of figuring out whether the content is for
them???

-- 
	Viktor.