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

[Chris Smith]

For what it's worth, I agree with you both that it's important to document
the laws, and that it's not the most friendly way to begin the
documentation for a reader who is unfamiliar with the concept.  It's not
clear to me whether the documentation ought to be optimized for readers who
are or aren't familiar with the concept, but I lean to the latter, which
means putting the type class laws at the end (but still easily accessible)
makes sense to me.

On Thu, Sep 16, 2021 at 7:47 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/018a9ae9/attachment.html>