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

[Viktor Dukhovni]

On Thu, Sep 16, 2021 at 06:51:42PM -0400, David Feuer wrote:

> The last time I went to look at the laws it took me a couple minutes to
> find them. I use them to write instances. Pretty important, IMO.

I agree the laws are important to document, I just don't think they
belong at the top of the module.  The beginner to intermediate users
will be using the library and existing instances for some time before
they start to write their own instances.

If more modules adopt something like the style of the new Data.Foldable,
experienced users will know to look for the laws at the end, if not
still present at the top of the module.

Of course perhaps the community would prefer the original Laws first
format, I'm fine with that emerging as the consensus.  Perhaps worthy
of a separate thread (made it so).

Of course the conjectured users who might most benefit from not being
intimidated by being exposed to laws before they're ready to understand
them might not be present on this forum...

-- 
    Viktor.