Choo: Incorporate IRC feedback for documentation

[yoshuawuyts]

Feels like we should improve the narrative, and work on the "why" behind the concepts. Probably related to #198. Full log:

03:23:38 <substack> is there a good pattern for populating state in models
  with initial data from a db that is async?
03:24:10 <substack> the part I don't see exactly is how to trigger the
  initial effect
03:24:38 <yoshuawuyts> substack: if it's a one-off and doesn't respond to any
  external factors you could create a subscription that then calls a reducer to
  update the full state
03:25:29 <yoshuawuyts> generally subscriptions seem to work well for
  bootstrappy things
03:25:48 <substack> ok I will try it, but seems complicated
03:25:57 <substack> there isn't something like app.send()?
03:26:39 <yoshuawuyts> we've talked about it, but providing app.send() would
  enable an escape hatch outside of the model `choo` enforces
03:27:53 <yoshuawuyts> I know `choo` is super frameworky but that's by
  design so that in a team setting the architecture is confined to what `choo`
  has laid out, even though it might create a bit of friction
03:29:20 <substack> ok it seems that subscriptions will work for what I need,
  looking at it more
03:29:41 <substack> kind of hard to follow the docs in the choo readme
03:30:50 <yoshuawuyts> substack: does this graph help?
  https://github.com/yoshuawuyts/choo/pull/198/files
03:31:26 <yoshuawuyts> svg version
  https://gist.github.com/yoshuawuyts/62305bfb8804a9e124818cb3061609a4
03:31:30 <substack> I think that makes it worse
03:32:38 <yoshuawuyts> Ah, that's unfortunate will need to find a way to
  better convey the model then
03:32:50 <yoshuawuyts> any suggestions would be heaps welcome
03:32:55 <substack> I think the readme should include more examples and talk
  less about the architecture
03:33:33 <substack> and have sub-sections for each sub-component of the view,
  model, and router sections
03:34:26 <substack> for example a heading of # model that introduces what a
  model is for by example and subheadings ## model effects, ## model state that
  discuss each property in isolation
03:35:32 <yoshuawuyts> Yes, that seems like a sound suggestion
03:35:37 <substack> and I haven't found the examples in example/ to be very
  helpful
03:36:22 <substack> because for me the main question I have about how all of
  this fits together is "why?" not "how"
03:36:31 <substack> a flow-chart answers "how" but not "why"
03:38:34 <yoshuawuyts> yeah, you're right it's about a paragraph per
  concept max at the moment mostly focused on implementation, with an extra
  API section for even more implementation
03:38:47 <yoshuawuyts> hmmm should def expand this
03:39:20 <yoshuawuyts> used to have "common actions" in there, but took it
  out (and forgot to put it in the handbook)
03:39:33 <substack> I also feel like there is not much flow between the
  topics, no narrative structure
03:39:33 <yoshuawuyts> alright, more "why" got it
03:39:58 <substack> which for this kind of project may be useful in conveying
  the concepts better
03:40:26 <substack> I'm also not necessarily suggesting the readme should be
  longer, but organized differently
03:42:46 <yoshuawuyts> hmmm, so what I'm thinking right now is to hook into
  the philosophy secion
03:42:49 <yoshuawuyts> *section
03:43:19 <yoshuawuyts> move from "why the framework" to "why these high level
  concepts" to "why the concepts inside the model"
03:43:36 <yoshuawuyts> where I feel the concepts inside the model are
  probably the hardest to understand, so would need most attention
03:44:24 <yoshuawuyts> you're right in pointing this out. Subscriptions only
  has a two-sentence description
03:44:28 <yoshuawuyts> that's not good enough
03:45:03 <yoshuawuyts> substack: thanks for the feedback!
03:45:33 <yoshuawuyts> I'm going to create an issue for this before I tap out
  tonight

Any help in pointing out concepts which were hard to understand / better phrasing / rewrites of sections would be heaps welcome. Thanks! :sparkles:

[toddself]

This has been on my mind recently as I was upgrading to 3.0 -- i've got a few thoughts I want to try to hammer out this weekend on examples and more detailed documentation in the readme itself (since that's where people are going to make their initial assessment)

[MattMcFarland]

The Readme as is, is what sold me on choo and I am not sold easily. The architecture stuff was what did it as well. I think the Readme is fine, maybe we can add another doc file?

[YerkoPalma]

I think that is time to update the choo site :smiley: Detailed guide, API reference and the Handbook are perfect topics for the site IMO.

[yoshuawuyts]

More from IRC:

20:12:15 <substack> would there be any reason why reducers wouldn't trigger from an event originating from a subscription?
20:13:24 <substack> also I keep getting this error: Uncaught AssertionError: barracks.store.start.send: cb should be a function
20:14:47 <substack> ok I see, I had to pass in `done` as the last arg to send()
20:14:59 <substack> that was very counter-intuitive
20:16:53 ⇐ Mackseraner quit  ↔ contraha_ and jabbs popped in  ↔ contrahax nipped out  
00:15:07 <yoshuawuyts> substack: yeah, def agree - the base API isn't *that* great - but if you think about the send() function as a CPS system where control is delegated I've found it easier to reason about
00:15:51 <yoshuawuyts> that analogy breaks down for view -> model tho; so it's not entirely true
00:16:38 <yoshuawuyts> substack: based on your feedback from a couple of weeks back (too many args in most methods) I figured out a way to reduce it by allowing different async methods
00:16:58 <yoshuawuyts> patch just needs merging, but then https://github.com/yoshuawuyts/choo-pull/ should work
00:17:21 <yoshuawuyts> docs and examples could use some work, but the general idea should be there I think
00:46:51 ↔ jabbs popped in  
00:53:39 <substack> I think it might also help if the docs for subscriptions referred to send() as a different
00:53:42 <substack> name
00:53:57 <substack> it's a positional argument, so its name isn't defined by the API, only by the documentation
01:00:38 <yoshuawuyts> substack: ah yeah, good point - since they're no longer equivalent it makes sense to call them differently
01:01:11 <yoshuawuyts> maybe "call" inside the model; which you need to pass a "callback" that calls back
01:01:36 <yoshuawuyts> plays into the CPS telephony system, could create a whole analogy around that
01:02:05 <substack> works for me

[yoshuawuyts]

@MattMcFarland I hear you. What I'm thinking is making the README more accessible by providing more narrative around the architecture so that people get a deeper conceptual understanding; especially coupled with good examples that would be grand I think

@YerkoPalma hah yeah the site def needs updating (help welcome!). I bought choo.io the other day, so we could place it in a better location. Would be heaps cool to give the docs their own special place on there; possibly "ecosystem" too in the form of the "awesome" list. You reckon? :sparkles:

[MattMcFarland]

@yoshuawuyts What help is needed?

[YerkoPalma]

@yoshuawuyts I think that a Roadmap in the website repo might help. Send PR so early may be too opinionated, because it isn't clear what will be included, or even what theme or design describe choo, I think some guidelines would help :+1:

[yoshuawuyts]

Closing because choo@5 will introduce a new API. See #425 for the merged PR. Thanks!