Beginner-friendliness of Validated doc

[ceedubs]

There has been some feedback on Gitter that the Validated doc isn't as beginner-friendly as it could be. Pretty early in the doc it delves into writing a parallelValidate method, discussing Apply, etc. This offers some nice insight into deriving Validated methods, but it's not necessarily obvious that a user doesn't need to write these things in their code. It would likely be better for users if the docs first showed simple examples of using Validated to accumulate errors and then in an advanced section at the end covered more advanced concepts and derivation.

[yilinwei]

Me and @zainab-ali have been discussing this problem since we've run several coding dojos/workshops over the past few months on typelevel libraries.

In my view, people who are interested in cats fall roughly into 3 categories

1. People who want to understand how cats works and why it works that way. These people have usually gone through the red book and gain most from a discussion of the datatypes, the typeclasses required for them to exist as well as a one liner about how you should use them.
2. People who just want to use cats to make there jobs a little easier. These people typically will only care about the bare minimum amount of syntax and types needed to achieve the task and a few nice examples of usages to make there lives easier (for validated it would be something like the mapN methods or something like .traverse).
3. People who are complete beginners to FP. These people require a build up from something a bit more basic (for example constraining the accumulated error to a NonEmptyList[Throwable]) and need some hand holding through some of the combinators that groups 1 & 2 would be familiar with such as map.

The documentation in cats can't cater to all 3 groups at once. It's never been clear to me who the docs are for.

[zainab-ali]

IMO I don't think the cats docs should cater to complete beginners to FP. The red book, already listed under resources for learners, does a much better job of that.

I think it's possible to cater to people who want to use it, and also to people who want to understand how it works. A good way to do this would be to:

1. Pose a common problem that Validated can solve. The current docs do this using config parsing.
2. Show how Validated solves that problem without going into detail about how it works
3. Explain a little bit about how Validated works (e.g. it has a valid / invalid case and uses a semigroup to accumulate errors)

I'd go as far as saying that most data type docs should have this kind of format.

I don't think the docs need to go into detail about the implementations of typeclass instances. A nod to the code should be enough for people who want to investigate those.

Aside from Validated, I think that there could be a few more cats based tutorials helping people hop from the red book to cats. As @yilinwei mentioned, we've done a few workshops in the past, so are probably in a good position to do that.

EDIT: For the record, that repo was done a while back, and doesn't use sbt-tut or even the most recent version of cats. There are plenty of ideas in the finally tagless space that we could expand on too. I'm aware it could be much improved.

[kailuowang]

Thanks very much for your inputs @zainab-ali and @yilinwei. These are valuable experiences when it comes to creating a documentation that serves the community the best.
I agree with @zainab-ali's view that it's difficult for cats' documentation not try to cater to complete beginners of Scala or FP. See the comment I made here. 👍 the strategy @zainab-ali is proposing.

[ceedubs]

@yilinwei @zainab-ali thanks for the input. @zainab-ali the general strategy that you propose sounds good to me.

Does anyone feel ambitious and want to give this a spin? :)

[yilinwei]

@ceedubs @kailuowang

We're set on doing a cats hackday again at the next London typelevel hack the tower event. The last time we did cats was ~ 5m ago and cats was still version 0.3.x so it's good to do it with an up to date version.

It would be useful to have some up to date docs for cats since we get people of various different abilities and allow them to follow along at their own pace if we can. If people don't mind we can do it as part of the preparation, though it will take a little bit of time because we need to plan out the session properly first.

[kailuowang]

@yilinwei, that will be awesome. Timing wise I don't see this as urgent as well. The focus of 1.0.0-MF is API. So I think we can schedule this for 1.0.0-RC1.

[ceedubs]

@yilinwei sounds fantastic! I don't think that we really need to tie this to a particular milestone.

[kailuowang]

Agree with @ceedubs we don't need to tie it to a milestone

[AlejandroME]

Can I take this? I'm new but I'm willing to collaborate!

[zainab-ali]

I'd be happy for you to! The hackdays have been postponed for a while, hence I haven't felt the pressure to take this up. There are other aspects of the docs that would benefit from attention apart from Validated, so there's still plenty for me to focus on.

[AlejandroME]

Hello,

I've just pushed the first commit (WIP) approaching this issue. Since this is my first contribution and because of the previous discussion about the detail level of this documentation, I want to get feedback about this first step.

The first two paragraphs of the actual doc mix two use cases: form validation and configuration validation, but then the developed example is the latter one. I provided a step-by-step example of Validated with the form-validation use case, first making the comparison with Either and then showing the approach with Validated.

If that example is suitable then I'll proceed to develop the usage of some combinators like conversions (.toEither, .toOption, .toIor, .bimap).

In regard to the configuration validation example, the only thing that I've changed was the title introducing it ("Another case").

I apologize in advance if there's some grammar error or typo.

[zainab-ali]

It's shaping up really well. I've had a quick look and made a few suggestions, but it would be worth getting feedback from others too.

[AlejandroME]

Thank you @zainab-ali for the feedback!

I'll work on it this week and I hope to polish some details and create a PR for this :)