hiebj / stately

elegant, type-safe state management
2 stars 1 forks source link

Usage Guides: create runnable code examples alongside plaintext explanations for Stately components #15

Open hiebj opened 5 years ago

hiebj commented 5 years ago

One or more ObservableHQ Journals showing live snippets of React code using various Stately tools would be very useful for documentation purposes, as part of a usage guide.

A contrived example for each of the three major components would be helpful - Subscribable, Controllable and Async.

more advanced and interesting real-world examples would be helpful as well, such as a search bar and a form (complete with read, create, update, delete). The AsyncOperations that are given could communicate with browser storage or the ObservableHQ platform instead of calling real APIs.

hiebj commented 5 years ago

Once helpful usage guides are created for stately-react, the README for stately-async can be simplified. It is unlikely that anyone will use stately-async without the react component wrappers, so it can probably be safely considered an "advanced tool"; the API docs generated by typedoc should be sufficient.

stately-reducers on the other hand is likely to be used on its own, so it should have its own usage guides. It is probably not necessary to create Observable journals, however.

hiebj commented 5 years ago

Since Subscribable, Controllable, and Async are each separate concepts, it probably makes sense to create a separate journal demonstrating each one. An additional fourth journal demonstrating combined, "real-world" use cases that make use of all three would be nice to have.

Each of the four journals could be expanded, maintained and improved over time.