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

[Keith]

Perhaps it would make sense to have a 'using the class' section and a 'writing instances' section. 
The first would focus on more concrete and intuitive examples.
The second would explain how and why to follow the laws, maybe with specific ways to avoid pitfalls and extra work (e.g. when you can and can't DeriveFoldable, when to use `foldMapDefault` when to define only `foldr` or `foldMap` or to use `toList` to define others.

It's super important that folks gan define legal instances so things don't brow up in their faces (e.g. an Applicative instance that zips but defines `pure` as a singleton). But often all they need to know is `DeriveTraversable` exists and works as long as you don't define things in strange ways (like conceptually reversed lists).
--Keith
Sent from my phone with K-9 Mail.

On 17 September 2021 08:30:37 UTC, Ignat Insarov <kindaro at gmail.com> wrote:
>Hello Viktor.
>
>Thank you for your continuous effort.
>
>I have been writing Haskell for years now and even getting paid for
>it. I care nothing for the laws — I rarely apply equational reasoning.
>I am a visual person, to me intuitive grasp is the tool of choice. I
>also know a few newcomers to Haskell and I am certain they make zero
>use of the laws.
>
>My thus informed view is that laws are fine in the end and useless at the start.
>
>On Fri, 17 Sept 2021 at 04:48, 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.
>_______________________________________________
>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/20210917/34bcb5fe/attachment.html>