Docs WIP

CHANGES.md

@@ -1,8 +1,10 @@
 ## 0.9.0 (2016.12.DD)  Unreleased
 
+Dr Ford has created a new re-frame narrative, and Bernard some infographics. Anyone seen Delores?
+
 #### Headline
 
-  - The README and `/docs` have been substantially reworked.
+  - The [README](README.md) and [/docs](/docs/README.md) have been substantially reworked.
   - [#218](https://github.com/Day8/re-frame/issues/218) Make it okay to use `subscribe` in Form-1 components. This is a big deal.
 
 #### Breaking

docs/MentalModelOmnibus.md

@@ -15,9 +15,8 @@ The tutorials initially focus on the **domino
 narrative**. The goal is to efficiently explain the mechanics of re-frame,
 and get you reading and writing code ASAP.
 
-**But** there are other interesting perspectives on re-frame
-which will deepen your understanding of its design,
-and help you to get the best from it.
+**But** there are other perspectives on re-frame
+which will deepen your understanding.
 
 This tutorial is a tour of these ideas, justifications and insights.  
 It is a little rambling, but I'm hoping it will deliver for you 
@@ -41,7 +40,7 @@ at least one "Aaaah, I see" moment before the end.
 ## What is the problem?
 
 First, we decided to build our SPA apps with ClojureScript, then we
-choose [Reagent], then we had a problem. It was August 2014.
+choose [Reagent], then we had a problem. It was mid 2014.
 
 For all its considerable brilliance,  Reagent (+ React)
 delivers only the 'V' part of a traditional MVC framework.

docs/WIP/Flow.md

@@ -75,7 +75,7 @@ It is important to the design of re-frame that event processing is async.
 On the end of the queue, is a `router` which (very soon) will:
  - pick up events one after the other
  - for each, it extracts `kind` of event (first element of the event vector)
- - for each, it looks up the associated event handler and called it
+ - for each, it looks up the associated event handler and calls it
   
  
 ## Between 2 and 3
@@ -83,17 +83,17 @@ On the end of the queue, is a `router` which (very soon) will:
 I lied above.
 
 I said the `router` called the event handler associated with an event.  This is a 
-useful simplification but we'll see in future tutorials that there's more going on.
+useful simplification, but we'll see in future tutorials that there's more going on.
 
 I'll wave my hands about now and give you a sense of the real story. 
 
 Instead of there being a single handler function, there's actually a pipeline of functions which 
-we call an interceptor chain. 
+we call an interceptor chain. The handler you write is inserted into the middle of this pipeline.
 
-This pipeline manages three things things:
+This function pipeline manages three things:
   - it prepares the `coeffect` for the event handler (the set of inputs required by the handler)
-  - it calls the handlerevent 
-  - it handles the `effects` produced by the 
+  - it calls the event handler (Domino 2)
+  - it handles the `effects` produced by the event handler  (Domino 3)
  
 
 The router actually looks up the associated "interceptor chain", which happens to have the handler wrapped on the end.