diff --git a/CHANGES.md b/CHANGES.md
index a2a1a61..60779fa 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -2,8 +2,8 @@
#### Headline
- - Docs: a rewritten README and a new "Introduction" section in `/docs`
- - [#218](https://github.com/Day8/re-frame/issues/218) Make it okay to use `subscribe` in Form-1 components
+ - 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. This is a big deal.
#### Breaking
diff --git a/docs/ApplicationState.md b/docs/ApplicationState.md
index d1be34b..2d812cb 100644
--- a/docs/ApplicationState.md
+++ b/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
-earlier, but now I'm thumping the table and my face is red with intensity. You need one.
+You really need a schema for `app-db`.
-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
-after every single event has been processed.
+Of course, that means you'll have to learn [spec](http://clojure.org/about/spec) and there's
+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:
+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:
https://www.youtube.com/watch?v=VNTQ-M_uSo8
***
diff --git a/docs/CodeWalkthrough.md b/docs/CodeWalkthrough.md
index 23b2585..cf258e7 100644
--- a/docs/CodeWalkthrough.md
+++ b/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**.
+
## Table Of Contents
@@ -35,42 +39,34 @@ 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).
-
-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?
+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).
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,
- like "#CCC", for the time display
+ - provides a single text input field, into which you can type a hex colour code,
+ 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)
+To run the code:
+ * Install Java 8
* Install leiningen (http://leiningen.org/#install)
Then:
-1. `git clone https://github.com/Day8/re-frame.git`
-2. `cd re-frame/examples/simple`
-3. `lein do clean, figwheel`
-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
+ 1. `git clone https://github.com/Day8/re-frame.git`
+ 2. `cd re-frame/examples/simple`
+ 3. `lein do clean, figwheel`
+ 4. open http://localhost:3449/example.html
## Namespace
-Because this example is so small, the code is in a single namespace.
-Within it, we'll need access to both `reagent` and `re-frame`.
-So, we start like this:
+Because this example is tiny, the code is in a single namespace which you can find here:
+https://github.com/Day8/re-frame/blob/master/examples/simple/src/simpleexample/core.cljs
+
+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]
diff --git a/docs/MentalModelOmnibus.md b/docs/MentalModelOmnibus.md
index 5faf168..1baf5f8 100644
--- a/docs/MentalModelOmnibus.md
+++ b/docs/MentalModelOmnibus.md
@@ -8,6 +8,9 @@ patterns of thought that produced that government are left intact,
then those patterns will repeat themselves.
> -- Robert Pirsig, Zen and the Art of Motorcycle Maintenance
+
+
+
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
-of these ideas, justifications and insights. It is a little rambling, but
-I'm hoping you'll have had at least one "Aaaah, I see" moment before the end.
+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
+at least one "Aaaah, I see" moment before the end.
@@ -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 ...
diff --git a/images/mental-model-omnibus.jpg b/images/mental-model-omnibus.jpg
new file mode 100644
index 0000000..abd45b8
Binary files /dev/null and b/images/mental-model-omnibus.jpg differ