Docs WIP

README.md

@@ -10,7 +10,7 @@ axe of my family? And because it has changed gently over time, it is still a pre
 y'know. Pretty good.
 
 > -- Terry Pratchett, The Fifth Elephant <br>
-> &nbsp;&nbsp;&nbsp; apparently reflecting on identity, flow and derived values
+> &nbsp;&nbsp;&nbsp; reflecting on identity, flow and derived values
 
 
 [![Clojars Project](https://img.shields.io/clojars/v/re-frame.svg)](https://clojars.org/re-frame)
@@ -32,11 +32,12 @@ Perhaps:
 3.  You're taking a [Functional Design and Programming course](http://www.eli.sdsu.edu/courses/fall15/cs696/index.html) at San Diego State University
     and you have a re-frame/reagent assignment due.  You've left the reading a bit late, right? I remember those days.
 4.  You know Redux, Elm, cycle.js or pux and you're
-    interested in a ClojureScript implementation, with a data oriented design.
+    interested in a ClojureScript implementation, **with a data oriented design**.
     In this space, re-frame is very old, hopefully in a Gandalf kind of way.
     First designed in Dec 2014, it even slightly pre-dates the official Elm Architecture,
-    although thankfully we were influenced by early-Elm concepts like `foldp` and `lift`.  We took a slightly
-    different path and, over time, re-frame pioneered concepts like event handler middleware,
+    although thankfully we were influenced by early-Elm concepts like `foldp` and `lift`, as well as 
+    terrific Clojure projects like [Pedestal App], [Om] and [Hoplon]. Since then,  
+    re-frame has pioneered ideas like event handler middleware,
     coeffect accretion, and de-duplicated signal graphs.
 5.  Which brings us to the most important point: re-frame is impressively buzzword compliant. It has reactivity,
     unidirectional data flow, pristinely pure functions,
@@ -45,6 +46,10 @@ Perhaps:
     xkcd reference (soon) and a hilarious, insiders-joke T-shirt,
     ideal for conferences (in design).  What could possibly go wrong?
 
+[OM]:https://github.com/swannodette/om
+[Hoplon]:http://hoplon.io/
+[Pedestal App]:https://github.com/pedestal/pedestal-app
+
 ## re-frame
 
 re-frame is a pattern for writing [SPAs] in ClojureScript, using [Reagent].

docs/ApplicationState.md

@@ -1,6 +1,4 @@
-- [On Data](#on-data)
-- [The Big Ratom](#the-big-ratom)
-- [The Benefits Of Data-In-The-One-Place](#the-benefits-of-data-in-the-one-place)
+## Application State
 
 
 #### Table Of Contents
@@ -54,9 +52,9 @@ seems a more useful paradigm than plain old map-in-atom.
 Further Notes:
 
 1. `app-state` would probably be a more accurate name, but I choose `app-db` instead because 
-    I wanted to convey the database notion as strongly as possible.
+    I wanted to convey the in-memory database notion as strongly as possible.
 2. In the documentation and code, I make a distinction between `app-db` (the `ratom`) and 
-   `db` which is the (map) `value` currently stored **inside** this `ratom`. Be aware of that naming.
+   `db` which is the (map) `value` currently stored **inside** this `ratom`. Be aware of that naming as you read code.
 3. re-frame creates and manages an `app-db` for you, so
    you don't need to declare one yourself (see the 1st FAQ if you want to inspect the value it holds).
 4. `app-db` doesn't actually have to be a `ratom` containing a map.  It could, for example, 
@@ -95,7 +93,7 @@ snapshots. All very efficient.
 For certain categories of applications (eg: drawing applications) this feature is borderline magic. 
 Instead of undo/redo being hard, disruptive and error prone, it becomes trivial. 
 **But,** many web applications are not self contained 
-data-wise and, instead, are dominated by data sourced from an authoritative remote database. 
+data-wise and, instead, are dominated by data sourced from an authoritative, remote database. 
 For these applications, re-frame's `app-db` is mostly a local caching 
 point, and being able to do undo/redo its state is meaningless because the authoritative
 source of data is elsewhere.
@@ -125,6 +123,10 @@ https://www.youtube.com/watch?v=VNTQ-M_uSo8
 Also, the mighty Rich Hickey (poor audio):<br>
 https://vimeo.com/195711510
 
+### How do I inspect it?
+
+See FAQ #1
+
 *** 
 
 Previous:  [This Repo's README](../README.md)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;