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

Beginner-friendliness of Validated doc #1678

Closed
ceedubs opened this issue May 18, 2017 · 13 comments
Closed

Beginner-friendliness of Validated doc #1678

ceedubs opened this issue May 18, 2017 · 13 comments

Comments

@ceedubs
Copy link
Contributor

ceedubs commented May 18, 2017

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

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

zainab-ali commented May 18, 2017

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

kailuowang commented May 19, 2017

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

ceedubs commented May 19, 2017

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

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

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

ceedubs commented May 19, 2017

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

@kailuowang
Copy link
Contributor

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

@AlejandroME
Copy link
Contributor

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

@zainab-ali
Copy link
Contributor

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 pushed a commit to AlejandroME/cats that referenced this issue Aug 27, 2017
This commit is the first approach to address typelevel#1678, developing the
form-validation example.
@AlejandroME
Copy link
Contributor

AlejandroME commented Aug 27, 2017

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

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

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

AlejandroME pushed a commit to AlejandroME/cats that referenced this issue Sep 9, 2017
This commit contains a simple form-validation example and a couple
of approaches making use of `Validated`.
It aims to solve typelevel#1678
kailuowang pushed a commit that referenced this issue Sep 26, 2017
* [WIP] Beginner-Friendly `Validated` docs

This commit is the first approach to address #1678, developing the
form-validation example.

* Beginner-friendly example of validated.

This commit contains a simple form-validation example and a couple
of approaches making use of `Validated`.
It aims to solve #1678

* Use of `tut` for code checking

- The code examples for form validation are now using `tut` with
its respective output in the generated .html.
- Fixes some structural issues (`Either` return type in the `Validated`
example, use of `mapN` instead of `|@|`).
- Adds a deprecation notice about cartesian builder and changes this
for using `.mapN`.

* Fixes failing `tut` snippet.

- The `Validated` approach with the for-comprehension has been
splitted in two: the instructions that compile and the for-comprehension
that doesn't compile. For the first ones, I've used `tut:silent` and
for the second one I've used `tut:book:fail`. With this, all the code
of this proposal is checked by tut correctly.
- Adds an import for Either to bring .flatMap in Scala versions prior
to 2.12.x.

* Fixes

- Fixes indentation in all the snippets (two spaces).
- Added a new section ("short detour") in where I explain the
`Semigroup` role in the accumulation, with a little portion of
`Validated` code.
- Adds "Back and forth" section explaining how to convert between
`Validated` and `Either`. I can't figure it out how to convert from
`Either` to `Validated` 'failing slowly'.

* Revamped some parts of this docs

- Added `final` modifier to `RegistrationData` case class.
- Changed if-else in `Either` example to `Either.cond`.
- Reused `Either` example validations in `Validated` (non-compiling)
approach with `.toValidated`.
- Deleted redundant imports for tut.
- Changed `Validated` of a `NonEmptyList` for `ValidatedNel` type alias.
- Deleted 'disclaimer' about converting from `Validated` to `Either`,
losing the fail-slow functionality.
- Added `Semigroup` example based on the Peter's one but in the
context of the example provided here.
- Fixed some typos and grammar errors.
- Pointed out to the cats `Semigroup` documentation instead of Wikipedia.
@LukaJCB LukaJCB closed this as completed Nov 16, 2017
@stew stew removed the ready label Nov 16, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

7 participants