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

Docs docs docs #1443

Closed
3 of 18 tasks
adelbertc opened this issue Oct 27, 2016 · 9 comments
Closed
3 of 18 tasks

Docs docs docs #1443

adelbertc opened this issue Oct 27, 2016 · 9 comments

Comments

@adelbertc
Copy link
Contributor

adelbertc commented Oct 27, 2016

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

Data types

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

I am working on the Traversable Functors section right now.

@adampingel
Copy link

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

fommil commented Mar 28, 2017

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

mgttlinger commented Mar 28, 2017

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

fommil commented Mar 28, 2017

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

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

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

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

ceedubs commented Sep 30, 2018

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.

@ceedubs ceedubs closed this as completed Sep 30, 2018
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

7 participants