Docs revamp

[jvanbruegge]

As explained at CycleConf I will work (hopefully with the help of others) on the docs. It will be more a very long tutorial, like a book, starting simple, ending at #705

Planned chapters:

• Getting started (setting up a project)
• Streams
• First component
  • Rendering static content
  • Handling events
  • Having local state
  • Making our input controlled
• Adding @cycle/http
  • Display empty profile pictures
  • Loading profile pictures from an API
  • Loading old chat messages from the server
  • Refresh button
• Multiple components
  • Splitting our first component in two
  • Creating a parent component to manage everything
  • Child context versus parent context
  • Manually converting sources and sinks between those contexts
  • Using @cycle/isolate to automatically convert contexts
• Basic @cycle/state
  • Implementing multiple chat rooms
  • Cleaning up our state management
  • Avoiding duplicated state with simple lenses
  • Adding a "is typing..." indicator
  • MVI
• Using @cycle/time
  • Adding timestamps to messages
  • Creating our first unit test
• Writing our first driver
  • What they are, and list of examples
    • cycle-pusher
    • cycle-selection-driver
    • cycle-deepstream
    • cycle-gun
    • https://github.com/cyclejs/react-native#other-native-drivers
  • Implementing a basic logging driver
  • Create a read-only websocket driver
  • Make the websocket driver bidirectional
• Advanced @cycle/state
  • Make the chatrooms individual components
  • Using makeCollection to dynamically instantiate chatroom components
  • Creating a lens to keep track of unread messages
  • Adding user profiles to messages
  • Using lenses to implement message filters
• Authenticating against an API
  • Creating a login window
  • Simple routing with @cycle/history
  • Implementing a higher order component to intercept HTTP requests
  • Allow to fetch your own user profile
• Creating a complex custom driver
  • Source as class
  • Implement a driver to save chat messages in indexed-db
  • Retrieve data from the db with our driver

---

Cookbook

• But I totally forgot

---

Glossary

• Component
• Lens
• more

---

• FAQ
  • Resetting an text input on an click event -> Link to chapter 2.4
  • Integrate bootstrap components (snabbdom hooks)
  • DOM attributes do not update as they should
  • Using lenses with makeCollection -> Link to chapter 8.2
  • Type 'MemoryStream<Response> & ResponseStream' is not assignable to type 'Stream<Response>'.

---

• API
  • @cycle/dom
  • @cycle/history
  • @cycle/html
  • @cycle/http
  • @cycle/isolate
  • @cycle/state
  • @cycle/time
  • @cycle/run
  • @cycle/rxjs-run
  • @cycle/most-run

[mightyiam]

This would be fantastic.

[staltz]

A few more ideas of tooling: https://www.npmjs.com/package/remark-graphviz or https://github.com/temando/remark-mermaid

[jvanbruegge]

The chapters of the tutorial section are now final, but feel free to still suggest stuff

[janat08]

Should be in typescript since its rather mandatory with undefined streams.

[janat08]

The official ts documentation is obtuse, no section for types alone, apparently outdated, and doesn't rely on inference.

[theJian]

What about adding a simple UI test section under First Component.

[IssueHuntBot]

@issuehuntfest has funded $60.00 to this issue. See it on IssueHunt

[brucou]

I am including some feedback received on gitter that can be insightful for the work in-progress regarding the documentation (:point_up: September 21, 2019 4:09 PM and ☝️ September 22, 2019 10:54 PM:

Hiya all! I've been reading through the cycle js guide over the past week and have been excited to check it out. But I tried to get started this afternoon using create-cycle-app one fits all, and felt quite overwhelmed by the boilerplate it created! Lots of imports I don't recognise, and concepts the guide didn't cover... I found myself deciding to try another new framework for my app. But thought I'd share here first in case anyone has experienced this before. I was excited to try FRP in practise
For context, I've read many tutorials on functional programming, built a basic app in elixir, dabbled with elm (mostly the tutorial), used regular streams in node, and have built many apps in Vue and react. Just thought at least you might appreciate feedback from a "beginner"

@brucou I went through and wrote down the bits that were unfamiliar after reading the guide (https://cycle.js.org/getting-started.html through 'Components')
Overall, I think routing is the biggest shock. The guide doesn't cover that, it uses multiple libs (including one outside the @cycle scope), and it's referenced in several files rather than just contained in one place (in fact much of the boilerplate seems to be for routing). Perhaps an additional page in the guide for how routing works would be a good bridge?

Beyond that, the drivers.ts file is just doing a couple things that I don't understand why they're necessary. For instance, in the guide, the drivers object is always just a simple object. In this everything's wrapped in a function, and there's a whole function just to execute each function, and then we're computing the driver names but omitting one of them and adding in two others for some reason. And there's several imports that weren't in the guide (withState, routerify, switchPath) which I can mostly infer but still had to lookup their readmes to get what's going on
I wish I could also provide suggestions for improvements! All I've got for now is adding a page on routing to the guide (maybe introducing withState as well?). I hope my feedback is constructive. I can imagine it's hard to find the right balance between something accessible to beginners and something useful for regular users.
IMO vue's cli finds that balance really well with its plugin ecosystem (you're asked whether you want to include a router and central state management as part of the install prompts, optionally adding additional plugins later and there's no need to ever eject) though that was a big undertaking