There is just a thing that I think could be improv...

# arrow

[Davio]

There is just a thing that I think could be improved in the Arrow docs and that's pointing out for which use cases you would use which kinds of solutions. A lot of stuff is documented pretty well if you already know what you want to use. But when you are thinking about adding Arrow to an existing code base, it's hard to understand where you'd use it; other than for typed errors maybe.

[simon.vergauwen]

I started this page, as kind-of a decision tree for what to use when. https://arrow-kt.io/learn/summary/

It's not yet completely incomplete, I am wondering if this is something people are looking for? It was kind-of inspired by https://reactivex.io/documentation/operators.html

This is also pretty cool, but looks hard to build and maintain 😅
https://rxjs.dev/operator-decision-tree

[simon.vergauwen]

I'd love feedback and what we currently have, what is missing and some nicer CSS 😂

[Alejandro Serrano.Mena]

on top of what Simon has mentioned, we also try to gather some general guidelines at https://arrow-kt.io/learn/design/

[simon.vergauwen]

Yes, we're open for everyone to contribute here, and feedback so we can continue to improve the learning experience for everyone

[Davio]

For me it's a bit of chicken-and-egg thing, as I don't really know its best use cases, there is a pretty large upfront investment to find out yourself where it fits and what kind of code you would refactor so I wouldn't know how to change the docs. Probably a brave soul needs to have made that journey and reflect to be able to tell us his experiences of where it helped 😄

[Davio]

And a personal issue is that Arrow leans pretty heavily on existing functional (theoretical) knowledge, such as whether an error is the left or right thing of an Either is something that can't get a foothold in my mind and have to look up every time. Compare this with Kotlin's Result which is a little easier to understand coming from an imperative language.

So if you come from a functional background and starting to use Kotlin then the transition to Arrow is definitely easier than coming from a Java OOP / imperative background. And it's this last group that I think needs the most help in deciding what to use, where and how.

[CLOVIS]

@simon.vergauwen about the 'summary' page, are the (guide) sections supposed to be links? They are underlined, but clicking on them just opens the section (at least on Chrome).

[CLOVIS]

It would be great if all function mentions in that page could be links to the related Dokka page; for example if recover(program, error) could be a link to https://apidocs.arrow-kt.io/arrow-core/arrow.core/recover.html… That's the main reason I don't have an external documentation website for my projects, it splits the documentation in two places and it's not easy to go from one to the other 😕

[Alejandro Serrano.Mena]

yeah, there should be links in the summary page... something else to figure out in the website 😕

[Alejandro Serrano.Mena]

about the general documentation, we try to go in the line between been concise for the regular user, and give enough information for a beginner... but in many cases you may also need a book or a course if you are not familiar at all with the content (some of the Arrow developers have developed such material for our books or trainings, so it would be great if at some point we could make that free of charge)

[dave08]

An extra point here is that the current docs just cover the surface of things -- not all the apis but just the general idea, and makes the user have to look up things in the source code. It might be nice to even just have a few tables spread out with the main overloads and functions for each module with a short description of when to use it and maybe a little example. Part of this is already in the KDocs... but by putting that in the docs in a summary, it would be a sort of an index (and the KDocs themselves aren't too useful in this aspect... since you have to navigate from page to page to compare functions, in a table it's all regrouped in a very clear way, and there can be multiple tables with categories/subcategories. A good example is in Optics, having one table for all the accessors/modifiers etc... another one for creating/composing lenses or similar from different types like list/set/etc...)