Write a ton of documentation

[djspiewak]

The existing documentation is okayish but needs a LOT of fleshing out.

[dhinojosa]

@djspiewak , I would love to help with docs. with your and the rest of the team's guidance. Anything, in particular, you would like first?

[djspiewak]

I think the first step is to roughly align what we have with what the hierarchy actually looks like. I did a rough search/replace on names when all the classes were renamed, an @LukaJCB removed (some of?) the old bits about ControlLayer, but we should take a pass over everything to make sure it's not talking about stuff that doesn't exist anymore.

Once we've done that, my rough general ideas fall somewhere along the following lines:

• A page talking about how the lifting works (this would mention MonadPartialOrder, but mostly just call out that instances are simply on companions and it's straightforward)
• An introduction page to the concept of MTL capability classes. Most people equate monad transformers with "complex nested types, terrible errors, and a lot of opaque lifting", and capability classes completely solve that problem. Beginning to get people thinking in terms of capability-declaring type signatures (this F has the capability to perform dependency injection with type R), that type of thing. The hardest leap is just reading the signatures and getting comfortable with the amount of abstraction floating around.
• A collection of use-cases. Dependency injection is a nice one because it's so obvious, but we can also talk about error channels and the like.
• I still think Chronicle is weird…

[baovitt]

@djspiewak, I'm very interested in writing documentation. I'm a beginner in Cats and feel that forcing myself to read through the codebase and understand the motivations enough to write documentation would be a great learning experience. Let me know what I can do.

Thanks,

Brad

[benhutchison]

• A collection of use-cases. Dependency injection is a nice one because it's so obvious, but we can also talk about error channels and the like.

Self-contained use case examples would be super helpful. Something a newcomer to MTL can copy, play with, and then modify to their needs.

The mtl docs currently have small examples for each class, but some examples showing pairs and "stacks" of mtl classes working together to solve a realistic problem would make a nice addition.

One use case I think there'd be a lot (perhaps too much!) interest in would be how to emulate the capabilities of ZIO using a mtl stack... 🤔 💭