Module documentation is not informative, or missing

[adam-arold]

📖 Documentation

I'm trying to understand how some of the constructs in fp-ts work but there are no good tutorials on the site and the module documentation is either non-existent or very uninformative. This is a good example:

Less strict in what sense? In this case, I was lucky because it was explained elsewhere what W means but it would be great if the docs explained with some code examples what the function was doing and how. This would help lower the barriers of entry for new users (especially for newcomers to the FP world).

This is an example of how documentation looks like in Java:

I'm not expecting Java-level documentation, it is just an example of how informative module docs can help a lot. I'm also willing to help as a contributor!

[steida]

@adam-arold https://gcanti.github.io/fp-ts/guides/code-conventions.html#what-a-w-suffix-means-eg-chainw-or-chaineitherkw

[steida]

This project takes million hours of free time of Giulio Canti so that's why he is focused on build not explaining stuff. Do not give up, it's worth it. You can learn a lot from tests. Learn only what you need and going to use.

[raveclassic]

Hey @adam-arold! Thanks for reporting this issue, the documentation is indeed incomplete. See more in my comment in the similar issue.

[SRachamim]

In the Java world the type signature of the function is not enough to tell the user how to use the function and what is the expected result. That's because there are many effects that could be going on that could not be reflected on type signature. This is why you need an encyclopedia for every function.

In fp-ts functions don't do anything which is not reflected on the type system. I'd say 80% of the time you can use the type signature as a documentation. 10% of the time you will have to also peak on the name of the function to understand it. The other 10% should have documentation.

Yes, you should feel comfortable with two things in order to use this library: TypeScript (e.g. generics) and functional programming (e.g. kleisli, monads, functors etc.). Those are prerequisites. There are few links to resources that explain it, but it's not the goal of this library.

Once you have those prerequisites, those four indicators are better than any written word in English:

• The type signature
• The name
• The category in which the function is documented
• The module in which the function is

That being said, the documentation should improve a lot.

[adam-arold]

This project takes million hours of free time of Giulio Canti so that's why he is focused on build not explaining stuff.

That's why I offered to help with documenting it.

In the Java world the type signature of the function is not enought to tell the user how to use the function and what is the expected result.

It is more or less the same here. Just by looking at a type signature I won't know why it is useful. A few code examples right above the type (like in my example) is a tremendous help and it doesn't take hours to produce it. For example I still don't understand why an applicative functor is useful. I can see the type signature, but I don't see the actual code that gains an advantage by using it.

Yes, you should feel comfortable with two things in order to use this library: TypeScript (e.g. generics) and functional programming

That's what I thought when I started using this, but as it turns out my knowledge is not deep enough. The point I'm trying to make is that it only needs a little push to add a huge amount of value to this library and I'm also willing to help document it.

I just didn't want to start opening PRs without knowing that they are welcome.

One final thing:

it's not the goal of this library.

The problem is that if you want to learn how to do FP properly you have to pick a library that implements all of the constructs you would need. Right now all libraries I checked (not just in Typescript) say that "we won't teach you". This greatly hinders industry adoption not just with Typescript but with all languages I've used in the last few years.

What I'm also seeing is that most folks know how to use an Either and that you can call map on it, but there is so much more to FP than this. There is a wide gap between entry-level FP and advanced FP and there are no comprehensive resources that would help one get there apart from some 500 page books about category theory.

All of this is really hard to see for someone who already knows how to do it.

TL;DR: I'm not asking you to do all the work, or to provide comprehensive tutorials, what I'm asking is whether it is OK for you if I try to add that little extra to the docs that would help my work and (probably) the work of all those folks who are at the impasse between novice FP and badass FP.

[chuckwondo]

@adam-arold I'm totally with you on this point.

TL;DR; I'd be happy to help with this effort of creating meaningful/helpful examples where they're needed, if such contributions are welcome.

I find it incredibly hard to bridge that gap as well, and I've also been trying to find resources to help bridge it. I've found some that help to some extent, but still fall far short of really connecting to the advanced concepts. Beyond the very basic FP concepts, the learning curve gets very steep, very fast, so it is understandable that writing/teaching to fill the gap is itself a difficult thing to do, which is perhaps why such resources don't exist (or at least I haven't managed to discover them, if they do exist).

I'm very grateful for all of the work @gcanti (and others) has (and continues to) put into the fp-ts ecosystem. As far as I've managed to grasp things, I think it is fabulous, and I've started to introduce small bits of it into my work, where I can keep it focused and comprehensible, in the absence of better resources for learning (and also perhaps teaching my colleagues, so that I can get them on board as well, not just to fp-ts and friends, but FP in general).