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

Getting Started Documentation #132

Closed
LandonSchropp opened this Issue Jul 3, 2017 · 2 comments

Comments

Projects
None yet
2 participants
@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's New?
  • Installing
  • API Reference
  • Known Issues
  • Migrating From...
  • Changelog

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:

  • What is Folktale?
  • Why would I use it?
  • What are the high-level concepts?
  • What are some basic examples of using Folktale?

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.

@robotlolita

This comment has been minimized.

Show comment
Hide comment
@robotlolita

robotlolita Jul 3, 2017

Member

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.

Member

robotlolita commented Jul 3, 2017

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

This comment has been minimized.

Show comment
Hide comment
@LandonSchropp

LandonSchropp Jul 8, 2017

Thanks for the reply! Even those short summaries are really helpful in revealing the intent of this library. I think the changes you suggested would be really helpful to somebody new to this package.

Thanks again!

Thanks for the reply! Even those short summaries are really helpful in revealing the intent of this library. I think the changes you suggested would be really helpful to somebody new to this package.

Thanks again!

robotlolita added a commit that referenced this issue Jul 10, 2017

@wafflebot wafflebot bot added the in progress label Jul 10, 2017

@robotlolita robotlolita closed this in #137 Jul 10, 2017

@wafflebot wafflebot bot removed the in progress label Jul 10, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment