robotlolita
commented
7 years ago Yeah, the landing page needs to be more helpful.
The documentation actually answers those questions right now, but instead of presenting them as a linear document that you can follow, or as cross-referenced sections, it has that conceptual documentation inside the API reference pages, on each submodule. This is quite messy and hard to navigate, I'll agree, but fixing this involves fixing some of the documentation tooling as well, so that'll take some time to solve.
I suppose a small "Overview" page could lessen this problem by linking to pages inside the API reference. This is not ideal, but at least would give people a way to see what's in the library and links to detailed information on each concept.
Conceptual pages for the modules are:
- core/lambda - tools for transforming and combining functions.
- core/object - utilities for working with objects as dictionaries and records.
- adt/union - modelling possibilities in data in a functional way.
- validation - a data structure that typically models form validations, and other scenarios where you want to aggregate all failures, rather than short-circuit if an error happens.
- result - A data structure that models the result of operations that may fail.
- maybe - A data structure that models the presence or absence of a value.
- concurrency/task - A data structure that models asynchronous actions, supporting safe cancellation and automatic resource handling.
These pages all follow the same basic structure. They start with a short description of what the module does, followed by a small example, followed by why they're useful, some use cases, and where relevant details on internal architecture and comparisons with other modules in the library. But, again, the tool used to generate those pages makes them really hard to navigate/discover :(
I'll try writing an overview page later this week. But solving the rest of the issues with the docs is going to take a bit more of time.
LandonSchropp
I'm brand new to Folktale. After reading the website's homepage, I wanted to learn more about the library, so I clicked on the Get Started button. This took me to the Docs page, but unfortunately, the links on that page weren't all that helpful:
What I'm really looking for is a Getting Started guide to be front and center. In particular, it would be great if it could answer these questions:
My next stop was Google, where I found this guide from the 1.0 version of the library. That's much more helpful, but it's also out of date, and it still doesn't answer all my questions.