Curate order of type class list in docs

[ceedubs]

http://non.github.io/cats//typeclasses.html has a list of type classes present in Cats. Currently it is dynamically generated in alphabetical order. The fact that it's dynamic and therefore we don't need to remember to update it is great. However, it would probably be nice to introduce the simplest type classes first and progress to the more complicated ones.

For example it almost certainly makes sense to learn Functor before Applicative, but currently Applicative is first in the list.

See this gitter conversation for motivation.

[ghost]

I've been reading through the docs and created a summary for each page that is currently done. For each page I listed what I considered was a pre-requirement (requires) for that page, based on the contents of that page. If a topic was mentioned but also explained, I marked this as repeats.

So an interesting example is Applicative that is discussed in terms of Monad. Monad is then introduced on its own page as "Monad extends the Applicative typeclass". So there is a circular dependency on the readers knowledge. Also, https://github.com/non/cats/issues/413 is also highlighted.

The other reason for this is to see how the structures of each page compares, so perhaps some general guidelines can be introduced - eg all pages have an implicit introduction that describes XX in a simple, non-technical way.

requires: [forcomprehensions]
repeats: []
# Getting Started


requires: [apply, functor, monad]
repeats: []
# Applicative
## Applicative Functors & Monads


requires: []
repeats[functor]
# Apply
### map
### compose
### ap
### ap2, ap3, etc
### tuple2, tuple3, etc
## apply builder syntax


requires: [applicative, apply, forgetfulfunctor, freemonad, functor, monad]
# Free Applicative Functor


requires: [arrow, applicative, functor, monad]
repeats: [adt, fixedpointfunctor, forgetfulfunctor, naturaltransform]
# Free Monad <!--- Empty --->
## What is it?
## Using Free Monads
### Study your topic
### Create an ADT representing your grammar
### Free your ADT
#### 1. Create a `Free` type based on your ADT
#### 2. Prove `KVStoreA[_]` has a `Functor`.
#### 3. Create smart constructors using `liftF`
#### 4. Build a program
#### 5. Write a compiler for your program
#### 6. Run your program
#### 7. Use a pure compiler (optional)
## For the curious ones: what is Free in theory?
### For the very curious ones
## Future Work (TODO)
## Credits


requires: []
repeats: [kindprojector]
# Functor
## Creating Functor instances
## Using Functor
### map
## Derived methods
### lift
### fproduct
### compose


requires: [comonad, functor, monad]
# Id 


requires: [arrow, applicative, apply, flatmap, functor, monad, split, strong]
repeats: [monadicfunctions, referentialtransparency]]
Kleisli.md
# Kleisli
## Functions
## Kleisli
### Type class instances
## Other uses
### Monad Transformers


requires: [applicative, functor]
repeats: [forcomprehensions, monadtransformer]
# Monad
### Monad instances
### flatMap
### ifM
### Composition


requires: []
repeats: []
# OptionT
## Reduce map boilerplate
## Beyond map


requires: [algebra.semigroup]
repeats: [associative, semigroup]
# SemigroupK


requires: [stateT, trampoline]
repeats: [referentialtransparency]
# State
## Robots
## Pseudorandom values
## Purely functional pseudorandom values
## Cleaning it up with State
## Fine print

[ceedubs]

@danishin had some good input here.

@danishin here are some thoughts I have on what you've said.

I definitely agree that Functor -> Apply -> Applicative -> Monad is a good progression (though the Apply/Applicative piece might change a bit if we follow through with a monoidal representation).

I didn't realize Id was listed with our type classes. I don't think this is a type class. Should it be moved to the "Data Types" section?

I also agree that Semigroup -> Monoid -> SemigroupK is a logical progression (and it could probably be followed by MonoidK. I think these might even be more familiar concepts than the Functor track, so maybe these should come first?

I might suggest Foldable -> Traverse instead of Traverse -> Foldable. I think Traverse is a bit more complicated, since it is more powerful and also extends Functor.

What do you think?

[danishin]

@ceedubs

I agree that Id should be placed in "Data Types" section.

As for Functor - Monad vs. Semigroup - Monoid path, I'm not sure. I personally think Monad track is a little more important than Monoid and Monoid should be a forked digression from Monad by introducing the similarity between the paths as in

Monad is a structure that defines a way to combine (the results of) functions.
Monoid is a structure that defines a way to combine objects.
from here

And regarding Foldable -> Traverse, yeah I meant the opposite. Traverse is a concept that builds upon Foldable, not the other way around, thus should be introduced afterwards.

I think when it comes to learning these typeclasses, it's quintessential to show how things connect & build upon each other. For me, reading this SO answer was definitely a revealing moment, being able to connect two seemingly very different concepts, Monad and Monoid.

[stew]

I never intended to leave those typeclasses as a list that just gets barfed into the end of typeclasses.html, I just never got around to presenting the material in a better way. I'm thrilled if someone is looking into this :)

[non]

@danishin I guess I feel like the Functor[F[_]] progression and the Semigroup[A] progressions are somewhat orthogonal. I feel like they could go in different sections.

For example, I don't think understanding Monad is required to understand Monoid (I learned about monoids first) but I also don't think Monoid is necessary for Monad either.

[danishin]

@non

I agree that both concepts are orthogonal in theory and should be treated as such when introducing to minimize confusions, but nonetheless, I do think that it's useful to document the connection as more of an insight.

By doing so, we can provide a broader generalization / abstraction over these different concepts. But as noted, I agree they need to be introduced separately and only generalize them afterwards. After all, all there is to category theory in CS is to provide abstractions / containers over different stuffs in order to be combined in a useful fashion.

[non]

Right, that would be a good point to make in a tutorial relating category theory to the library's design.

[fommil]

This confused the hell out of me. Trying to use scala-exercises to guide me but there are still cyclic deps, Traverse/Reader