Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Ordering for type classes on microsite #1420

Closed
adelbertc opened this issue Oct 22, 2016 · 7 comments
Closed

Ordering for type classes on microsite #1420

adelbertc opened this issue Oct 22, 2016 · 7 comments

Comments

@adelbertc
Copy link
Contributor

adelbertc commented Oct 22, 2016

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
Copy link
Member

tpolecat commented Oct 22, 2016

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 - SemigroupMonoid
  • Applicative and Traversable Functors - FunctorApply/ApplicativeTraverse
  • Monads - FunctorApply/ApplicativeFlatMap/Monad
  • Variance and Functors FunctorContravariantInvariant
  • 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
Copy link
Contributor Author

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
Copy link
Member

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

@juanpedromoreno
Copy link
Contributor

@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:

screen shot 2016-10-23 at 13 32 20

What do you think?

@adelbertc
Copy link
Contributor Author

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
Copy link
Member

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
Copy link
Contributor Author

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants