Documentation refresh for monad transformers
This PR came out of a discussion in the Typelevel discord with @djspiewak and @armanbilge regarding unexpected interactions with monad transformers and Cats Effect.
This PR moves around monad transformer documentation to better reflect that it is a more advanced topic:
- updates the monad transformer documentation
- to move the overview to a separate section instead of the jump start guide
- change uses of
FuturetoTryto avoid suggesting developers use the deprecated Future instances - add a Pitfalls section to warn users about unfortunate interactions with CE and direct users to Cats MTL as an alternative.
- moves the Monad Transformer documentation pages out of Data Types to their own section.
I also made a few related changes for consistency:
- remove the pointless Datatypes index pages that just listed all the datatype page links
- move the Typeclass page to and Overview page under the Typeclasses section.
- fix a broken link in guidelines.md
To minimize these pitfalls, monad transformers should only be used as locally-scoped utilities to reduce boilerplate. Do not include monad transformers in public method signatures. Calling code can always use monad transformers themselves.
@typelevel/cats Anyone strongly disagree with this advice?
This PR has a somewhat large diff, but the focus of it is calling out this often repeated advice (and less examples with Future, and calling out more gotchas).
I should perhaps note, "strongly disagree" isn't the only option 😆 Adding more nuance is totally good too!