Incorporate IRC feedback for documentation

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! ✨

[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? ✨

[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