Rewrote documentation on the IO monad to reference cats-effect

[djspiewak]

Closes #1624

Ping @ceedubs. I'd also like to hear @alexandru's and @mpilquist's thoughts on the wording. I wanted to make it clear that cats.effect.IO is an easy and minimal default, while the typeclasses should ensure that the space of alternatives remains coherent and should be viable (or even preferable) under most circumstances.

[ceedubs]

Thanks @djspiewak!

This looks really good to me. There's only one piece that I wasn't sure about:

Notably, cats.effect.IO does not provide any mechanism for achieving parallel computation (though such functionality can be built on top of it, which is what libraries like fs2 achieve). For these and other needs, we would invite you to consider one of the other Task-like data types within the cats ecosystem, such as Monix's Task.

fs2 is mentioned in one sentence and then Monix in the next. To me it kind of reads like fs2 is a side-note, while Monix's Task is what we'd recommend for io-with-parallelization. Is there another way to word this that would make it clearer what the relationship between cats-effect/fs2/monix is?

[alexandru]

👍 for me the working is clear, fs2 is mentioned as building on top of cats.effect.IO, while Monix's Task is mentioned as an alternative.

Well, maybe make the FS2 mention a proper sentence, instead of a mention in parens :)

Btw, we the library authors aren't the target here. Maybe we should just ask for feedback from beginners about what they feel about this description.

[ceedubs]

Thanks for your input @alexandru.

Reading through this again after a fresh night's sleep, I'm not sure exactly what my hold up was yesterday. 👍

Since this is a clear improvement over what we currently have, is a documentation change, and has signoff from @djspiewak, @alexandru, and me, I'm going to go ahead and merge it. Thanks @djspiewak!

[djspiewak]

We can flesh out the wording more in a separate PR if we feel it's appropriate. The reason I didn't think fs2 merited a stronger mention (despite the fact that it's my own subjectively preferred option) is because it doesn't actually provide an IO alternative, unlike Monix. I wanted to make it clear that Monix's Task is out there, and an equally valid option for end-users who need a concrete Effect type. I probably would have made stronger mention of fs2 if their Task was still present.

If we want to add a separate section, How does functional concurrency work?, I wouldn't be averse, though I think that probably belongs more in the cats-effect docs. It's definitely a very frequently asked question from newcomers to the ecosystem.