Ordering for type classes on microsite

[adelbertc]

Currently they're in alphabetical order: http://typelevel.org/cats/typeclasses.html

We probably a want more natural ordering, here's a strawman proposal:

Type Classes

Semigroup
Monoid

Functor
Cartesian (missing)
Applicative (Apply merged into here)
Traverse
Monad/FlatMap

Foldable
Reducible (missing)

Invariant
Contravariant

SemigroupK
MonoidK
Alternative (missing)
MonadCombine
MonadFilter

ApplicativeError/MonadError (missing)
MonadReader (missing)
MonadState (missing)
MonadWriter (missing)

Bifunctor (missing)
Bifoldable (missing)
Bitraverse (missing)

I omitted Id, not sure why that's under type classes. Also omitted Show since that's covered in the base page.

This is assuming the current set of tutorials we have. We probably want some others in there like FlatMap, but we can deal with those later.

/cc @juanpedromoreno our sbt-microsite extraordinnaire
@tpolecat since I know he has a lot of thoughts about this stuff

[tpolecat]

I think there are a lot of crisscrossing paths through this stuff, so I wonder if it would make sense to organize it into a set of "tracks", each with its own introduction and progression. Some chapters would be appear in multiple tracks.

For example:

• Semigroups and Monoids - Semigroup → Monoid
• Applicative and Traversable Functors - Functor → Apply/Applicative → Traverse
• Monads - Functor → Apply/Applicative → FlatMap/Monad
• Variance and Functors Functor → Contravariant → Invariant
• etc.

Above I have kind of folded Apply and FlatMap into the corresponding "big" type classes. Although these things are legit abstractions they're rarely used and I don't think they warrant a lot of attention in beginner doc.

The relationship between Foldable and Traverse is so strange that I don't know if it's worth mentioning. It requires you to know how a bunch of stuff works.

[adelbertc]

Yeah that makes sense. The troubles of reusable abstractions ;)

@juanpedromoreno Not sure if you have any ideas around this, is it possible to support a structure like @tpolecat suggested?

[tpolecat]

The side menu definition in the sbt-microsites plugin should allow you to reference the same page more than once, seems like.

[juanpedromoreno]

@adelbertc @tpolecat Both alternatives look good.

About the first one, it's already possible. We need to add the weight metatag to the different markdown documents and it should work. In fact, that is how scala-exercises organized the cats library:

https://www.scala-exercises.org/cats

Regarding the second alternative, it also would be possible with some tweaks. For instance, the menu definition (data/menu.yml) would look like as follow:

options:

  ############################# 
  # Type Classes Menu Options #
  #############################

  - title: Type Classes
    url: typeclasses.html
    menu_type: typeclasses
    menu_section: typeclasses

  - title: Semigroups and Monoids
    url: typeclasses/semigroup.html
    menu_type: typeclasses
    menu_section: semigroupsandmonoids

    nested_options:
     - title: Semigroup
       url: typeclasses/semigroup.html
       menu_section: semigroupsandmonoids
     - title: Monoid
       url: typeclasses/monoid.html
       menu_section: semigroupsandmonoids

  - title: Applicative and Traversable Functors
    url: typeclasses/functor.html
    menu_type: typeclasses
    menu_section: aplicative

    nested_options:
     - title: Functor
       url: typeclasses/functor.html
       menu_section: aplicative
     - title: Apply
       url: typeclasses/apply.html
       menu_section: aplicative
     - title: Applicative
       url: typeclasses/applicative.html
       menu_section: aplicative
     - title: Traverse
       url: typeclasses/traverse.html
       menu_type: typeclasses
       menu_section: aplicative

  - title: Monads
    url: typeclasses/functor.html
    menu_type: typeclasses
    menu_section: monads

    nested_options:
     - title: Functor
       url: typeclasses/functor.html
       menu_section: monads
     - title: Apply
       url: typeclasses/apply.html
       menu_section: monads
     - title: Applicative
       url: typeclasses/applicative.html
       menu_section: monads
     - title: Monad
       url: typeclasses/monad.html
       menu_type: typeclasses
       menu_section: monads

  - title: Variance and Functors
    url: typeclasses/functor.html
    menu_type: typeclasses
    menu_section: variance

    nested_options:
     - title: Functor
       url: typeclasses/functor.html
       menu_section: variance
     - title: Contravariant
       url: typeclasses/contravariant.html
       menu_section: variance
     - title: Invariant
       url: typeclasses/invariant.html
       menu_section: variance

  - title: Foldable
    url: typeclasses/foldable.html
    menu_type: typeclasses

  - title: MonadCombine
    url: typeclasses/monadcombine.html
    menu_type: typeclasses

  - title: MonadFilter
    url: typeclasses/monadfilter.html

...

  ########################### 
  # Data Types Menu Options #
  ###########################

  - title: Data Types
    url: datatypes.html
    menu_type: data

  - title: Const
    url: datatypes/const.html
    menu_type: data

  - title: Either
    url: datatypes/either.html
    menu_type: data

  - title: FreeApplicatives
    url: datatypes/freeapplicative.html
    menu_type: data

  - title: FreeMonads
    url: datatypes/freemonad.html
    menu_type: data

  - title: Kleisli
    url: datatypes/kleisli.html
    menu_type: data

  - title: OneAnd
    url: datatypes/oneand.html
    menu_type: data

  - title: OptionT
    url: datatypes/optiont.html
    menu_type: data

  - title: State
    url: datatypes/state.html
    menu_type: data

  - title: Validated
    url: datatypes/validated.html
    menu_type: data

In this second case, I'm not sure if the result (it would be a very long menu) would be intuitive when you are trying to find a concrete typeclass:

What do you think?

[adelbertc]

Hm I think if we explain what the meaning of the ordering is on the Type Classes page it might be OK. We could further order the top-level categories to give more visibility to common ones, like have the Monads series up top or something. I'll ping on Gitter for feedback.

[tpolecat]

I think each track should have a short introduction before the first TC doc, so you have some idea of what it's about and the kinds of constructions it will introduce.

[adelbertc]

I like that idea. We have a company hackthon this Wed - Fri so I'm planning on rehauling some of the Cats docs for this. Will keep this in mind as I do it - keep the suggestions coming!