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

[David Feuer]

I'm not talking about whether they're first or last. They're currently not
part of the class documentation *at all*. They're only in the
Data.Traversable documentation.

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

> 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.
> _______________________________________________
> 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/e22dcea6/attachment.html>