Docs docs docs

[adelbertc]

In light of the new docs I think we should revisit our docs and update them to better reflect the new ordering. Going to use this ticket to track TODO's and in-flights.

Type classes

• Type classes Revamp type classes doc #1440
• Semigroup and Monoid Revamp Semigroup doc #1442
• Traversable Functors Revamp Functor, Applicative, Traverse doc #1513
  • Functor
  • Apply/Applicative
  • Traverse
• Monads
  • Functor
  • Apply/Applicative
  • FlatMap/Monad
• Variance and Functors
  • Invariant
  • Functor
  • Contravariant
• Universal algebra
  • SemigroupK/MonoidK
  • Alternative/MonadCombine
• MTL (Monad{Reader, Writer, State, Error})

Data types

• Eval
• Option/OptionT
• Either/EitherT
• Validated
• Reader/ReaderT/Kleisli
• State/StateT
• Writer/WriterT
• FreeApplicative
• Free
• Const
• NonEmpty{List, Vector}

[adelbertc]

I am working on the Traversable Functors section right now.

[adampingel]

If I can make a request of the docs here:

I was just reading through the pages for Free Monad and Free Applicative. I noticed this is the only place where the notion of an algebra is discussed. It would be helpful to either define it inline or link to the definition being used in those two docs.

[fommil]

I am forming some thoughts on the docs, but I'm not sure how long it will be before I have something constructive to add. Generally I feel many big problems are structural. e.g. getting to the docs (typelevel.org has a tendency to send people to github), ordering of entries.

But the most important is the lack of an introduction / motivation. The current docs definitely assume a lot of the reader. I think it can only be called a success when an OOP Java dev can read it after Odersky's book and get it.

My preference would be to use gitbook or something similar that will create a PDF version as well as online, much like the Shapeless Guide. I strongly believe that the Scala FP paradigm needs a single book (which can be big!) that takes OOP devs and hand holds them to writing apps with cats. Anything short of this makes it an impenetrable niche style of development most suited to Haskell developers.

The red book has some fantastic sections to it, but I'd argue that it's as useful as a Haskell book on FP to somebody wanting to learn cats. The motivating examples are very very good, but I am unsure how much of that material we can re-use without entering copyright infringement territory. The best thing about it was the way it introduced problems that seemed very difficult and solved them very easily, then showed that it was actually the same FP pattern repeated. If we could get runar/paul's permission to convert some of these sections to cats, I think it would be incredibly useful material.

We also need a single sheet cheetsheet of things like summaries of typeclasses / data types and typical type problems and solutions (e.g. the classic traverse requirement).

Any time I read an extraordinary intro to FP I document it here http://ensime.org/learning_scala/ My current thinking is that All roads lead to lambda has been the most absolutely convincing argument for the Free Monad I've seen... very compelling to Java. I work with a lot of non-FP Scala developers and I am here to remind us that we're the weirdos in the corner using Monads and need to explain why we're doing it to the naysayers 😄

I'd be interested in getting involved, but to do structural things I think a few high level structures need to be proposed and perhaps even discussed IRL as sticky notes.

[mgttlinger]

Imho the selling point to get the OO guys hooked is effect capturing structures like Option because everybody can relate to those pesky NullPointerExceptions. From there you can sell Functor, Applicative, Monad as a way to use those in a practical manner.

(I have the beginnings of a talk on that which I can contribute to the docs once it is finished)

[fommil]

@mgttlinger I don't agree with that. It's simply not a pain point. The biggest selling point to OO developers, in my experience of talking to very sceptical / traditional developers, is being able to take the mocking pattern further and factor out async in their tests. Writing async tests is a massive PITA. OO devs get really annoyed with Option because it just means they have to do a getOrElse(throw new ...) everytime someone hands it to them.

[mgttlinger]

@fommil That's interesting because the guys at work got why Option etc is great rather quickly and use it but still resort to traditional mocking/testing stuff because they do not want to learn about Freer etc. But it may just be the team I work in. Who knows 🤷‍♂️

[ChristopherDavenport]

I agree with @mgttlinger as far as the ways that I am able to convince people to start picking up FP paradigms for devs who come for OO backgrounds. We definitely need a more complete resource as @fommil suggests to advance people in practical as well as theoretical underpinnings.

As far as getOrElse(throw new ...) I have found that pain point also serves as a great transition into the power of ADT's, where I dont mention the scary sounding Co words, except with those who have already transitioned into FP.

Regardless, if the docs are being spruced up making them more palatable to less-experienced developers is always the way to go. Even so far as warning which areas are more difficult if necessary.

[kailuowang]

From my experience, people coming to cats because they already want to do, or try, pure FP in scala. Even if they do not already know what FP is about, they at least have some preconceived notions about it.
The sheer size of cats makes it rather intimidating to entice people to the FP world. I mean when you come to cats, where do you even start? typeclass? Monad? Functor? Free?
There is already a good resource to gradually introduce new scala dev into the FP world, that's the red book. I don't see some paragraphs of cats documentation can achieve the same goal.

[ceedubs]

I'm going to go ahead and close this out as a stale issue. We don't have docs for everything yet, but we have it for many types, and this is the sort of issue that could hang around forever. We can open bite-size issues for any docs that are still missing.