Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Getting Started Documentation #132
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.
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:
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.