Better docs [to do]

[goshacmd]

This is a spike to organize thoughts and resources relating to docs. (Feel free to tag this one as a to-do or something)

As someone who's tried several existing side-effect models for Redux and Cycle, the README was just enough for me to see what this is about. However, this is not going to be the case for everyone, therefore we should consider an effort to improve the docs.

Throwing a couple of my thoughts:

• identify target audiences: redux-saga and redux-observable users
• appeal to TAs individually: maybe have separate sections about redux-cycle vs saga and redux-cycle vs redux-observable. pros and cons, differences in approaches
• observables are typeable, whereas generators are hard to type (yield can't be typed. yield* can, but it can't be used in the catch/finally blocks, greatly limiting their usefulness — this is something I discovered making redux-typed-saga)
• briefly introduce observables and Cycle.js and link to the official docs and other useful resources
• page on side-effect handling. common scenarios
• encourage custom drivers for side-effects (analytics, native functionality, etc; whereas the official docs seem to kind of oppose them)
• commonly needed functionalities translated from pure react/sagas/observables to redux-cycle
• more examples
• GitHub pages to host the docs

[goshacmd]

Regarding custom drivers, I can imagine there being several approaches:

• drivers for the lowest-level APIs, with higher-level wrappers to reduce friction.

  This is the approach Redux-Ship preaches, for one, and I tried incorporating it into my redux-typed-saga. It looks nice with the generators, but its viability is yet to be seen for Cycle.

  So if there were a driver for talking to the remote HTTP server, there could be a custom wrapper on top of it that's tailored to talking to a specific API server.

  I imagine this adds some boilerplate though if all you do is talk to the API. Even store the auth tokens somewhere and feed them each time.

• specialized drivers for common cases

  So if all you do is talk to some API, you could have it as a driver of its own, removing the boilerplate that you'd have for wrapping an HTTP driver. It could even take care of managing tokens and such. Furthermore, it also gives the benefit of being able to opaquely swap the transport mechanism, or add support for another one, like websockets.

I don't know what's better as I'm still exploring this territory. I'm currently trying specialized drivers for API and ANALYTICS in a client project. We'll see where it goes :)

[lmatteis]

Regarding custom drivers, perhaps the Cycle.js site/github is a better place for it. We shouldn't dictate best-practices for Cycle programs. After all this middleware simply bridges Cycle.js with Redux - it doesn't mix them.

[nickbalestra]

Agree on improving the docs, and all the points you mentions seems valid to me, I that documentation is where we should focus on (imho redux-observable did a good job in this regard we get some inspiration there perhaps?).

Once that is done we should try to spread the love (talks, ...)

[nickbalestra]

@lmatteis @goshakkk :On a side note, what do we think of moving this project under the cycle-js community organization? Or it's own org like redux-observable does? I think that if we work on the docs and site, that will also help.

[lmatteis]

I like the idea of a separate organization. I will set it up as soon as I get a chance. Regarding the site though, I think having a readme is enough - of course the readme needs better content but I don't think an actual gh-pages is needed.

[Widdershin]

Hi! Just wanted to say that I would love to welcome this project to the cyclejs-community organization, if that's what you decide to do. I think it would be a boon for the project's visibility, and long-term might help attract more maintainers.

[lmatteis]

@nickbalestra @goshakkk @Widdershin ok great! I've moved it over! I'm not sure about how permissions work though. I'll figure things out once I'm back from work trip this weekend.

[Widdershin]

@lmatteis I've given you admin permissions for this repo, so you can add anyone you like as a collaborator.

If you find yourself needing multiple repos, we can set up a team who all have appropriate permissions across all the redux-cycle-middleware repos.

[lmatteis]

@goshakkk @nickbalestra gave you guys write access

[lmatteis]

Closing this as the README is pretty exhaustive in my opinion.