Consider adding notes for different kinds of users

[davesmith00000]

Following a discussion on Discord, it was suggested (by @djspiewak) that I could raise an issue about missing docs. Please feel free to reject / re-write as you see fit. This is a bit of a brain dump.

@armanbilge has opened issues https://github.com/typelevel/cats-effect/issues/2928, https://github.com/typelevel/cats-effect/issues/2929, and https://github.com/typelevel/cats-effect/issues/2930 which cover a lot of my thoughts.

The main thing I would have found useful is notes aimed at different groups of people. The current docs are aimed at JVM users, if they are aimed at anyone at all. sbt, for example, has notes for plugin authors. I couldn't say who all the CE user types are, but in my case I fall into two groups:

1. Scala.js user - I rarely venture onto the JVM these days.
2. Library author/maintainer - I'm attempting to cats-effect-ify my existing library. I'm comfortable with pure functional programming and programming with Effect monads, but I'm a CE newbie.

Scala.js

In issue https://github.com/typelevel/cats-effect/issues/2928, we're discussing that while for the most part, running CE on a JS runtime should feel identical to using it on the JVM, there are still differences, particularly in the browser (as appose to Node.js).

In the browser, at least in my experience, you are unlikely to build an app that runs from main once you hit a certain level of complexity, which means not using IOApp. The debate about that is being covered in the other issue description so I won't go into it here. However it would be good to call that out in the docs, and explain the alternatives.

I'm often surprised by how few Scala folks have wrestled with the JS runtime (clearly I'm bias), so I think some discussion of how it differs from the JVM and what the implications of that are would be good too. You can preface it with "Cats effect allows you to treat them in a nearly identical fashion" by all means, but some brief notes on topics like the JS execution model and concurrency - just to raise awareness of the terminology even - would be good. A related subject could be something like setInterval vs setTimeout vs setImmediate vs requestAnimationFrame. Is cancellation even relevant in a browser setting (given the types of work / load / lifecycle of page entities etc)? How many people can answer that question? ...but maybe it's too much / out of scope ...the docs do already spend time talking about things like threads though so... 🤷

Practical examples would be good here too. We have examples of how to manage a file - not much of that happening in a browser though! How about an event handler?

Library maintainer

Granted, this might boil down to "Just do the usual thing", but a little bit of discussion on the things to be aware of as a library builder would be good.

What are current best / recommended practices?

I had an interesting discussion today about Haskell where (I'm told, don't shoot me) most libraries tend to just expose IO and people using the libraries lift IO into something else to meet their needs. Most CE code I've seen tends to use the kernel typeclasses, but "is that even interesting?" was the question I was challenged with. Your app probably wants to talk about capabilities rather than Async, your library effect type is probably usually "I need a maximum typeclass", and you can (at a cost) convert between concrete effect types. The typeclasses in theory allow you to seamlessly accept any effectful monad with a relevant implementation to hand (with no conversion cost, but at the expense of a muddier API) - ...better or worse? - but the runtime (IOApp again) is hard coded to IO anyway. That's totally reasonable, concrete implementations are going to need specific runtimes, but as a library author how do you recommend we build our libraries and frameworks around those constraints and considerations?

It feels like all of this stuff is 'known', there are many libraries out there doing this. But I can't find any of that written down anywhere (did not google hard enough maybe) so I'm making assumptions and trying to reinvent the wheel before ultimately asking around on Discord. Also using the libraries out there already as a reference point is the slowest way to figure this stuff out. And I'm impatience / time poor. 😄

--

I hope that's helpful. I am a cats effect new comer so do with this as you will, I shall not be offended if the ticket is closed as down because you feel I've missed the point or for any other arbitrary reason. I know writing documentation is hard going, thank you for all the hard work so far both in terms of the current docs and for the library itself!