Docs WIP

CHANGES.md

@@ -2,8 +2,8 @@
 
 #### Headline
 
-  - Docs: a rewritten README and a new "Introduction" section in `/docs`
+  - The README and `/docs` have been substantially reworked.
-  - [#218](https://github.com/Day8/re-frame/issues/218) Make it okay to use `subscribe` in Form-1 components 
+  - [#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/ApplicationState.md

@@ -115,13 +115,18 @@ source of data is elsewhere.
 
 ### Get You A Leveragable Schema
 
-You really do need a schema for `app-db`.  Yes, it is optional, and I breezed past this 
+You really need a schema for `app-db`.
-earlier, but now I'm thumping the table and my face is red with intensity. You need one.
 
-The [todomvc example](https://github.com/Day8/re-frame/tree/master/examples/todomvc) (in this repo) shows how to check `app-db` against your schema 
+Of course, that means you'll have to learn [spec](http://clojure.org/about/spec) and there's
-after every single event has been processed. 
+some overhead in that, so maybe, just maybe, in your initial experiments, you can 
+get away without one. But not for long.  Promise me you'll write a `spec`.  Good.
 
-This is good: <br>
+The [todomvc example](https://github.com/Day8/re-frame/tree/master/examples/todomvc)
+shows how to use a spec.  Look in `src/db.cljs` for the spec itself, and then in `src/events.cljs` for
+how to write code which checks `app-db` against this spec after every single event has been 
+processed. 
+
+Specs are leveragable. Watch how: <br>
 https://www.youtube.com/watch?v=VNTQ-M_uSo8
 
 *** 

docs/CodeWalkthrough.md

@@ -2,12 +2,16 @@
 
 ## Initial Code Walk-through
 
-At this point in your reading, you are armed with:
+At this point, you are about 50% of the way to understanding re-frame.  You are armed with:
  - a high level understanding of the 6 domino process (from re-frame's README)
  - an understanding of application state (from the previous tutorial) 
 
+By the end of this tutorial, you'll be at 70%, which is good
+enough to start coding by yourself.
+
 In this tutorial, **we'll look at re-frame code**.
 
+
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 ## Table Of Contents
@@ -35,24 +39,18 @@ In this tutorial, **we'll look at re-frame code**.
 ## What Code?
 
 This repo contains an example application called ["simple"](https://github.com/Day8/re-frame/tree/develop/examples/simple),
-which has around 70 lines of code. We'll look at every line of the [file](https://github.com/Day8/re-frame/blob/develop/examples/simple/src/simple/core.cljs).
+which has around 70 lines of code. We'll look at every line of [the file](https://github.com/Day8/re-frame/blob/develop/examples/simple/src/simple/core.cljs).
-
-You are currently about 50% the way to understanding re-frame. By the
-end of this tutorial, you'll be at 70%, which is good
-enough to start coding by yourself.
-
-## What Does It Do?
 
 This app:
  - displays the current time in a nice big, colourful font
- - provides a text input field into which you can type a hex colour code, 
+ - provides a single text input field, into which you can type a hex colour code, 
-   like "#CCC", for the time display
+   like "#CCC", used for the time display
-      
       
+Here's what it looks like:
 ![Example App image](../images/example_app.png)
 
 To run the code: 
- * Install Java 8  (http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
+ * Install Java 8 
  * Install leiningen  (http://leiningen.org/#install)
 
 Then:
@@ -62,15 +60,13 @@ Then:
   4. open http://localhost:3449/example.html
 
 
-The source file we'll be reviewing is:
-https://github.com/Day8/re-frame/blob/master/examples/simple/src/simpleexample/core.cljs
-
-
 ## Namespace
 
-Because this example is so small, the code is in a single namespace. 
+Because this example is tiny, the code is in a single namespace which you can find here:
-Within it, we'll need access to both `reagent` and `re-frame`. 
+https://github.com/Day8/re-frame/blob/master/examples/simple/src/simpleexample/core.cljs
-So, we start like this: 
+
+Within this namespace, we'll need access to both `reagent` and `re-frame`. 
+So, at the top, we start like this: 
 ```clj
 (ns simple.core
   (:require [reagent.core :as reagent]

docs/MentalModelOmnibus.md

@@ -8,6 +8,9 @@ patterns of thought that produced that government are left intact,
 then those patterns will repeat themselves. <br>
 > -- Robert Pirsig, Zen and the Art of Motorcycle Maintenance
 
+
+<img height="350px" align="right" src="/images/mental-model-omnibus.jpg?raw=true">
+
 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.
@@ -16,9 +19,9 @@ and get you reading and writing code ASAP.
 which will deepen your understanding of its design,
 and help you to get the best from it.
 
-This tutorial is a tour 
+This tutorial is a tour of these ideas, justifications and insights.  
-of these ideas, justifications and insights.  It is a little rambling, but 
+It is a little rambling, but I'm hoping it will deliver for you 
-I'm hoping you'll have had at least one "Aaaah, I see" moment before the end.
+at least one "Aaaah, I see" moment before the end.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -94,6 +97,7 @@ wrong places and you'll end up with a tire fire of an Architecture.
 
 ## It does Event Sourcing
 
+
 How did that error happen, you puzzle, shaking your head ruefully?
 What did the user do immediately prior?  What
 state was the app in that this event was so problematic?
@@ -124,6 +128,7 @@ Here's Martin Fowler's [description of Event Sourcing](http://martinfowler.com/e
 
 ## It does a reduce 
 
+
 Here's an interesting way of thinking about the re-frame 
 data flow ...