improve the readme

Author: zeke

README.md

@@ -3,53 +3,54 @@
 Geosockets is a Node.js webserver and javascript browser client for rendering website
 visitors on a map in realtime using WebSockets and the browser's Geolocation API.
 
-See the demo app at [geosockets.herokuapp.com](https://geosockets.herokuapp.com).
+See the demo app at [geosockets.herokuapp.com](https://geosockets.herokuapp.com) and
+the Heroku WebSocket Beta announcement at [blog.heroku.com/archives/2013/10/8/websockets-public-beta](https://blog.heroku.com/archives/2013/10/8/websockets-public-beta).
 
-### Using the Client Script on Your Site
+### The Client
 
-The Geosockets javascript client can be used on any website:
+[client.coffee](https://github.com/heroku-examples/geosockets/blob/master/client.coffee) is written as a node app that uses [Coffeeify](https://github.com/substack/coffeeify) (the red-headed step-child of [browserify](https://github.com/substack/node-browserify#readme)) and [Grunt](http://gruntjs.com/) to transpile the source into a single browser-ready javascript file.
 
-```html
-<link rel="stylesheet" type="text/css" href="https://geosockets.herokuapp.com/styles.css">
-<script src="https://geosockets.herokuapp.com/client.js"></script>
-<script>window.geosocket = new Geosocket("wss://geosockets.herokuapp.com");</script>
-<div id="geosockets"></div>
-```
+When the client is first run in the browser, a [UUID](https://github.com/broofa/node-uuid#readme) token is generated and stored in a cookie which is passed to the server in the headers of each WebSocket message. This gives the server a consistent way to identify each user.
 
-Use CSS to configure the size and position of the map container:
+The client uses the [browser's geolocation API](https://www.google.com/search?q=browser%20geolocation%20api) and the [geolocation-stream](https://github.com/maxogden/geolocation-stream#readme) node module to determine the user's physical location, continually listening for location updates in realtime. EOnce the WebSocket connection is establised, the client broadcasts its location to the server:
 
-```css
-#geosockets {
-  width: 100%;
-  height: 100%;
+```js
+{
+  uuid: '6e381608-2e63-4e40-bf6c-31754935a5c2',
+  url: 'https://blog.heroku.com/archives/2013/10/3/websockets-public-beta',
+  latitude: 37.7521248,
+  longitude: -122.42365649999999
 }
 ```
 
+The client then listens for messages from the server, rendering and removing markers from the map as site visitors come and go.
+
 ### The Server
 
 [server.coffee](https://github.com/heroku-examples/geosockets/blob/master/server.coffee) is a node app powered by [express 3](http://expressjs.com/guide.html), node's native [http](http://nodejs.org/api/http.html) module, and the [einaros/ws](https://github.com/einaros/ws/blob/master/doc/ws.md) WebSocket implementation. Express is used to serve the static frontend in `/public`.
 
 The server was designed with horizontal scalability in mind. The shared location dataset is stored in a redis datastore and each web dyno connects to this shared resource to pull the complete list of pins to place on the map. Clients viewing the map each establish their own WebSocket connection to any one of the backend web dynos and receive real-time updates as locations are added and removed from the redis datastore.
 
-### The Client
+### Embedding the Javscript Client on Your Site
 
-[client.coffee](https://github.com/heroku-examples/geosockets/blob/master/client.coffee) is also written as a node app. [Coffeeify](https://github.com/substack/coffeeify), the red-headed step-child of [browserify](https://github.com/substack/node-browserify#readme), is used in concert with [Grunt](http://gruntjs.com/) to transpile the client into a single browser-ready javascript file.
+The Geosockets JavasScript client can be used on any website:
 
-When the client is first run in the browser, a [UUID](https://github.com/broofa/node-uuid#readme) token is generated and stored in a cookie which is passed to the server in the headers of each WebSocket message. This gives the server a consistent way to identify each user.
+```html
+<link rel="stylesheet" type="text/css" href="https://geosockets.herokuapp.com/styles.css">
+<script src="https://geosockets.herokuapp.com/client.js"></script>
+<script>window.geosocket = new Geosocket("wss://geosockets.herokuapp.com");</script>
+<div id="geosockets"></div>
+```
 
-The client uses the [browser's geolocation API](https://www.google.com/search?q=browser%20geolocation%20api) and the [geolocation-stream](https://github.com/maxogden/geolocation-stream#readme) node module to determine the user's physical location, continually listening for location updates in realtime. EOnce the WebSocket connection is establised, the client broadcasts its location to the server:
+Use CSS to configure the size and position of the map container:
 
-```js
-{
-  uuid: '6e381608-2e63-4e40-bf6c-31754935a5c2',
-  url: 'https://blog.heroku.com/archives/2013/10/3/websockets-public-beta',
-  latitude: 37.7521248,
-  longitude: -122.42365649999999
+```css
+#geosockets {
+  width: 100%;
+  height: 100%;
 }
 ```
 
-The client then listens for messages from the server, rendering and removing markers from the map as site visitors come and go.
-
 ### Running Geosockets Locally
 
 If you're new to Heroku or Node.js development, you'll need to install a few things first:
@@ -66,22 +67,23 @@ cd geosockets
 npm install
 ```
 
-Fire up redis, a grunt watcher, and the node webserver at [localhost:5000/?debug](http://localhost:5000/?debug):
+The foreman [Procfile](https://github.com/heroku-examples/geosockets/blob/master/Procfile) defines the processes
+required to run the app. Fire up redis, a grunt watcher, and the node webserver at [localhost:5000/?debug](http://localhost:5000/?debug):
 
 ````
 foreman start
 ```
 
-## Debuggging
+### Debugging
 
-The client uses a custom logging function, found in `lib/logger.coffee`. This function
-only logs messages to the console if a `debug` query param is present in the URL, e.g.
+The client uses a [custom logging function](https://github.com/heroku-examples/geosockets/blob/master/lib/logger.coffee)
+that only logs messages to the console if a `debug` query param is present in the URL, e.g.
 [localhost:5000/?debug](http://localhost:5000/?debug). This allows you to view client
 behavior in production without exposing your site visitors to debugging data.
 
-## Testing
+### Testing
 
-Simple integration testing is done with [CasperJS](http://casperjs.org/), a navigation scripting & testing utility for [PhantomJS](http://phantomjs.org/). Casper is integrated into the app using the [grunt-casper](https://github.com/iamchrismiller/grunt-casper) plugin, and run with foreman. Each time you make a change to your client, the casper tests are run automatically.
+Crude integration testing is done with [CasperJS](http://casperjs.org/), a navigation scripting & testing utility for [PhantomJS](http://phantomjs.org/). Casper is integrated into the app using the [grunt-casper](https://github.com/iamchrismiller/grunt-casper) plugin, and run with foreman. Each time you make a change to your client, the casper tests are run automatically.
 
 ### Deploying Geosockets to Heroku