Give more visibility to the documentation

[OlivierBlanvillain]

I think the cats documentation is a bit hard to reach from the README, this is the expected path to SemigroupK:

• Land on https://github.com/typelevel/cats
• → click Documentation#website link
• → click Typeclasses
• → scroll down
• → click SemigroupK

As an example, I find it way more accessible on scalajs-react or scalacss :

• Land on https://github.com/japgolly/scalajs-react
• → click Router

My suggestion would be to give it more visibility on the README, for instance by adding a big pile of links like the following:

Documentation is here.

• Typeclasses:
  • Applicative
  • Apply
  • Contravariant
  • Faq
  • Foldable
  • Functor
  • Id
  • Invariant
  • Monad
  • Monadcombine
  • Monadfilter
  • Monoid
  • Monoidk
  • Semigroup
  • Semigroupk
  • Show
  • Traverse
• Data Types:
  • Const
  • Freeapplicative
  • Freemonad
  • Kleisli
  • Oneand
  • Optiont
  • State
  • Validated
  • Xor

[ceedubs]

@OlivierBlanvillain I totally agree that our docs aren't very discoverable. @non has a branch where he has done a bit of cleanup, but we still have a long way to go. Part of our strategy with his branch was to have less noise on the readme so that the things that are there are more noticeable.

It may be nice to have a big list of links like that, but I think there may be even better options. I think that #95 would provide the same information for the type classes but in a more digestible way (and would show the relationships between them). I also like the idea of something like the book of doobie that has a clear start point and progression for newcomers. People who are already familiar with cats are going to know how to get to the information that they want, so I am interested in focusing on people who aren't already familiar with cats and don't know which of the 20 items in the list they should click on to start with.

Sorry this is kind of a brain dump. In short, I definitely think we need to improve our docs, so thank you for speaking up about it.

[OlivierBlanvillain]

For a result similar to the book of doobie, I think that Gitbook could be a really good candidate. In a few lines of shell you can go from https://github.com/jto/validation/tree/v2.0/docs/src/main/tut to http://jto.github.io/validation/docs/book/, it also has a search thing which works pretty well. If you think that's a good idea I could give it a try on cats.

A type classes diagram looks sound really great :smile:

[ceedubs]

@OlivierBlanvillain oh wow that looks pretty nice. I remember @adelbertc mentioning Gitbook at some point, but I never took the time to look into it. It looks like in your example your code in your book is still compiled via tut - is that right? This looks great to me!

[OlivierBlanvillain]

Yes, it's .tut → .md → .html :). The last step is done via an open source node.js tool. https://www.gitbook.com/ makes it sound like it's all hosted but you can actually do everything locally.

[ceedubs]

@OlivierBlanvillain I realized that I never explicitly said this, but if you are interested in giving a cats git-book a try, I think that would be fantastic.

[yilinwei]

I really like the book of doobie, thanks for linking that!

I've been wanting to clean up the docs as well not just from a beginner perspective but as,

• migration/differences from scalaz
• library authors
• new contributors
• new users of FP

[zainab-ali]

Could we add experienced users of FP to that list? i.e. users who understand FP, but are new to the way it is implemented in cats.