update documentation

README.md

@@ -1,50 +1,62 @@
 # KnockoutJS APP Starter
 > Build Single-Page apps with KnockoutJS
 
-Rapidly prototype your next single-page application, with a `zero-build` out-of-the-box web-component solution. Need to go beyond the prototype stage, fret not, the tools are in-place to take you to production.
+Rapidly prototype your next single-page application, with a `zero-build` out-of-the-box web-component solution. Need to go beyond the prototype stage, fret ~~not, the tools are in-place to take you to production.~~
 
 This is as simple as possible, but no simpler
 
 *Designed for web componets in both legacy and modern browsers*
 
-### Features
+## Features
 
 - `KnockoutJS` 3.4.x
     - `Web Components` for reuseable UI
-- `Bootstrap` 3.x
+- `Bootstrap` 3.x for design
-- `JQuery` 1.11.x
+- `JQuery` 1.11.x to support bootstrap, and provide ajax
 - Based on `HTML5Boilerplate` 6.x
 - `ESLint` for coding style
-- `Jasmine` for testing
+- `Relay` a simple pub/sub utility for component communication, using knockout itself
-- `Gulp` for production builds
+
-    - `Rollup` to only export the code your using
+## Requirements
+
+[NodeJS]() is used to install `vendor/` dependencies and in the *future* provide a method to `build` your project for production via `gulp`
 
 ## Getting Started
 
-## Why Zero-Build?
+Lets bootstrap our app with
 
-**SPEED!**
+```
+npm install
+```
 
-A production pipe-line should *NOT* be in your way while developing...
+And move the `src/` folder where ever you want it
-
-...however, `npm build` adds it when you need it
-
-## How
 
 ## Project Structure
 
+```
+    src/                <-- your public app directory
+        app/            <-- knockoutjs config & startup
+        assets/         <-- your js, css, and images
+        components/     <-- web components
+        pages/          <-- html views that use web components
+        vendor/         <-- extenal dependencies, ie. things you did not write
+        index.html      <-- start here
+```
+
+## Documentation
+
+You can find extra documentation in the `docs/` directly, such as
+
+- [Relay]('docs/relay.md')
+
 ## Polyfills
 
-Todays "Evergreens" browsers support 99% of `ES6`, providing a pethra of capabilities, such as `import`, `class`, `fetch`, and `promise`.  Depending on your desired browser support, you may find a polyfill to suit your needs, **HOWEVER** this build is designed to work with IE8+
+While todays "Evergreens" browsers support 99% of `ES6` and provide a pethra of capabilities, such as `import`, `class`, `fetch`, and `promise` depending on your desired browser support, you may find a polyfill to suit your needs...
 
-...but such is beyond the scope of *this* starter package.
+...**HOWEVER** this build projects uses libraries designed to work with IE8+, but testing that is beyond the scope of this project
 
 ## TODO
 
-- add a ko.subscrible() utility to manage communication between components
+- add a simple router (riot-route)
-- add a simple router
 - add gulp build process for production builds
 - add Jasmine for testing
-- evaluate
-    - jquery migrate patch
-    - html5 shim

docs/relay.md

@@ -0,0 +1,60 @@
+# Relay
+
+> A dead-simple pub/sub utility for KnockoutJS
+
+I always have a `Relay` utility to communicate between web-components or services, for knockout it is just a simple wrapper around `knockout.subscribable()` functionality.
+
+## Getting Started
+
+First include `relay` in your knockoutjs config file located at `app/require.config.js` like so
+
+```
+    ...
+    paths: {
+        ...
+        "relay": "vendor/relay/relay"
+    },
+```
+
+Next, include it in your web-components `define` section
+
+```js
+define(['knockout', 'relay', 'text!./nav-bar.html'], function (ko, relay, template) {
+
+    return {
+        viewModel: function viewModel(params) {
+            var self = this;
+
+            // add relay.inbound / relay.outbound here
+        },
+        template: template
+    };
+
+});
+```
+
+Now your ready to start using the utility
+
+## Usage
+
+The API is dead simple, just 2 methods: `inbound` and `outbound`
+
+To send a message
+
+```js
+relay.outbound(message, channel);
+```
+
+Where `message` be any data, string, object, ect... and `channel` is how to pick it up on the other side
+
+```
+relay.inbound(channel, function(data) {
+    // do something with the data
+});
+```
+
+Thats it!
+
+### Reference
+
+- [Stackoverflow Example](https://stackoverflow.com/questions/26251773/knockout-components-communication)