additional documentation

CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+So you want to contribute, awesome.  **Thank you**.
+
+Bug reports and code and documentation patches are all welcome. You can help this project also by using the development version and by reporting any bugs you might encounter.
+
+You may contribute in several ways like:
+
+* Creating new features
+* Fixing bugs
+* Improving documentation and examples
+* Translating any document here to your language
+
+## Table of contents
+
+* [Contributing](#contributing)
+  * [Developing](#developing)
+  * [Running tests](#running-tests)
+  * [Reporting a bug](#reporting-a-bug)
+  * [Request a feature](#request-a-feature)
+  * [Commit message](#commit-message)
+  * [Code style](#code-style)
+
+## Developing
+
+For now, check out the read me and any documentation located in the `docs/` folder.
+
+> This should be expanded in the future, [want to help?](http://code.negative9.net/geoff/riot-starter/issues/new)
+
+## Running tests
+
+Running tests *should* be as easy as:
+
+```bash
+npm run test
+```
+
+> no client-side testing solution exists yet, [want to help?](http://code.negative9.net/geoff/riot-starter/issues/new)
+
+## Reporting a bug
+
+Use the [issue tracker](http://code.negative9.net/geoff/riot-starter/issues/new) to report any bug you find.
+Bugs description should include:
+
+* How to reproduce the bug;
+* Easy to understand title;
+
+Would be nice to have some code showing how to reproduce the code, you may use [gist](https://gist.github.com) or [Codepen](https://codepen.io) for uploading your example code.
+
+## Request a feature
+
+Use the [issue tracker](http://code.negative9.net/geoff/riot-starter/issues/new) to request a new feature.
+
+Keep in mind, this is for the minimalist.  Something that can be easly integrated into any project.
+
+## Commit message
+
+Commit messages should includes issue reference and a imperative easy to understand sentence.
+
+## Coding style
+
+If it is supported in all major browers without transpiling, then please use those JavaScript language features in your code, with one caveat -- readablity is king.
+
+Currently all ES5 and ES6/ES2015 are available.
+
+This project is linted agaist [ESLint](https://eslint.org/) and the [`.eslintrc.json`](.eslintrc.json) is dead-simple, and all you need to followed.
+
+Thank you for reading this.
+
+
+Hey, **star** this *repo* and/or share it with your friends.

README.md

@@ -1,83 +1,127 @@
 # RiotJS App Starter
-> A Rapid Application Starter kit for RiotJS
+> A Rapid Application Starter kit for RiotJS minimalists
 
-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 using [RiotJS](https://riot.js.org/) for the fastest way to iterate over UI for development -- **bar-none**. 
 
-This is built as simple as possible, but no simplier
+No crazy syntax, just HTML, CSS and JavaScript.   
 
-### Features
+No isolated eco-system, work with any library, any tool, any way you want! 
 
-- `RiotJS` 3.x
+[RiotJS](https://riot.js.org/) is tiny; tiny foot print, tiny API, and this leads it to be extremely fast to learn -- closest to web standards as you can get.
-    - `Web Components` for reuseable UI
-    - `Events` for communication
-    - `Route` for url navigation
-- `HTML5Boilerplate` 6.x static file base
-- `ESLint` for coding style
-- `Gulp` for production builds
 
-### Requirements
+What are you waiting for -- **GO FORTH AND BUILD YOUR APP, RAPIDLY!**
 
-[NodeJS](https://nodejs.org/) is used to install `vendor/` dependencies and a method to `build` your project for production via `gulp`
+*Designed to be as simple as possible, but no simpler*
 
-## Getting Started
+## Features
 
-1. Run `npm install` to load vendor dependencies
+- [RiotJS](https://riot.js.org/) 3.x give us the core UI building blocks
+    - `Web Components` for composable and reusable UI
+    - `Events` to communicate between components or other code
+- [Riot-Route](https://riot.js.org/api/route/) the simplest way to manage URL navigation
+- [Grayscale](http://n2geoff.github.io/grayscale/) Small, 2kb gzipped CSS framework with a layout focus
+- [Gulp](https://gulpjs.com/) is there for when your ready for *production*.  See [Build for Production](#build production) below
 
-2. Start coding in `src/public`
+**Requirements**
 
-3. run the `public/index.html` from your favorite web server\*
+- [NodeJS](https://nodejs.org/) 
 
-> \* try `live-server` from `npm` or via [Visual Studio Code]() plug-in
+> Installs `vendor/` dependencies and `npm build`  to get your project into production
 
 ## Why Zero-Build?
 
 **SPEED!**
 
-A production pipe-line should *NOT* be in your way while developing...
+A production pipe-line should *NOT* be in your way while **developing**. You should be able to iterate over your designs *FAST* , see those changes *FAST*, and when your ready, you should be able to build your solution *FAST* , but only as the final step -- not every step.
 
-...however, `npm build` is there when you need it
+`npm build` is still there. See Below.
 
-## How
+### How
 
-`RiotJS` is blazing fast, outside of a production build, this project uses the `runtime-compiler` that can easily handle thousands of tags/actions in hundreds of milliseconds.
+[RiotJS]() [client-size compiler](https://riot.js.org/online-compiler/) is blazing fast,  it only adds about 10kb, and it can easily handle thousands of tags/actions in hundreds of milliseconds.
 
-### Build
+## Getting Started
 
-When you are ready to move to production you can run `npm build`.  This will create a `dist` folder with all your optimized assets, web-components, vendor dependencies and remove the riot `runtime-compiler` to shave off another 100kb
+1. Run `npm install`, this will install all vendor dependencies
 
-Check out the [gulpfile]('gulpfile.js') for all the build options if you do not want to build everything.  Every task is commented, and split-up so you can grep it easily.
+2. Start coding in `src/public`
 
-## Project Structure
+3. run the `public/index.html` from your favorite web server\*
+
+> \* try `live-server` from `npm` or via [Visual Studio Code]() plug-in it's awesome!
+
+### Project Structure
 
 ```
-docs/                 <-- additional documentation
 src/
-    public/           <-- development is done here
+    public/           <-- develop here
        css/           <-- your css files
        js/            <-- your javascript files
+           app.js     <-- basic routing/utils bootstrap
        images/        <-- your images
        tags/          <-- web-components
        vendor/        <-- vendor dependencies, ie code you did not write
        index.html     <-- start here
        ...            <-- web meta files
+docs/                 <-- additional documentation
 test/                 <-- tests (one day)
 gulpfile.js           <-- task runner
 README.md
-...                   <-- project meta files
+...                   <-- misc project meta files
 ```
 
-## Polyfills
+### Web Components
 
-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...
+Web-components are just `HTML` files wrapped in a custom `tag`, which means they can be as simple as
+
+```html
+<my-component>
+    <button>
+        Say Hello!
+    </button>
+</my-component>
+```
+
+These files are usually saved as `my-component.tag`, but to get proper syntax highlighting the *norm* is keep them as HTML files naming them something like `my-componet.tag.html`
+
+> Save in the `tags/` folder, organize this however you like
+
+Of course we want our component to do more, so...
+
+...*for now*, go check out the [RiotJS GuideI](https://riot.js.org/guide/)
+
+
+## Build for Production
+
+When you are ready to move to production you can run `npm build`.  This will create a `dist` folder with all your optimized assets, web-components, vendor dependencies and remove the riot `runtime-compiler` to shave off another 100kb
+
+Check out the [gulpfile]('gulpfile.js') for all the build options if you do not want to build everything.  Every task is commented, and split-up so you can grep it easily.
 
-...but such is beyond the scope of *this* starter kit.
 
 ## Testing
 
 - TBD
 
+
+## Additional Documentation
+
+- [How Dependencies are Used]('docs/dependencies.md')
+
+
 ## TODO
 
-- integrate Jasmine for tests
+- Include a testing framework [Jasmine](https://jasmine.github.io/), [test.it](https://github.com/n2geoff/testit), or?
-- bring in ajax lib (n2geoff/riot-http) for non-es6 environments?
+- Is good AJAX support the missing ingredient?  or is`fetch` good enough? 
 - add routing example
+
+## Support
+
+Please open [an issue](http://code.negative9.net/geoff/riot-starter/issues/new) for support.
+
+## Contributing
+
+Anyone is welcome to contribute, however, if you decide to get involved, please take a moment to review the [guidelines](CONTRIBUTING.md), there minimalistic;)
+
+## License
+
+[MIT](LICENSE)

docs/dependencies.md

@@ -0,0 +1,38 @@
+# Frontend Dependencies
+
+I've always been hesitant using NodeJS for client-side dependency managment, but the `npm` package [frontend-dependencies](https://github.com/msurdi/frontend-dependencies) takes that away, and I did not want to commit any external vendor code here.
+
+With [frontend-dependencies](https://github.com/msurdi/frontend-dependencies) we can pull in just the dependency files we need, not an entire `node_modules` directory of cruft.  Infact, nothing is put into the `node_modules` directory!  By default, I just pull in 2 files for each dependency ( the develpment and the minified version)
+
+## Get Started
+
+Running `npm install` will install all the production build dependencies for when you need them and as a `postinstall` hook, will populate the `src/public/vender` directory will all the client-side dependencies.  These are name-spaced.
+
+You can add or remove dependencies from the `package.json` file.  Client-side dependencies are configured under `frontendDependencies`, which looks something like
+
+```
+"frontendDependencies": {
+    "target": "src/public/vendor/",
+    "packages": {
+        "riot": {
+            "version": "3.13.2",
+            "src": "*min.js",
+            "namespaced": true
+        },
+        "riot-route": {
+            "version": "3.1.4",
+            "src": "dist/route.*",
+            "namespaced": true
+        },
+        "grayscale": {
+            "src": "dist/*",
+            "url": "https://github.com/n2geoff/grayscale",
+            "namespaced": true
+        }
+    }
+}
+```
+
+I found this to be, currently, the simplest way to manage client-side dependencies.
+
+[Learn More](https://github.com/msurdi/frontend-dependencies) on the github page for the lib

gulpfile.js

@@ -70,5 +70,5 @@ gulp.task('assets', gulp.parallel('css', 'fonts', 'images', 'javascript', 'vendo
 // build everything for production distribution
 gulp.task('build', gulp.series('assets', 'public', 'index', 'tags'), () => {});
 
-// create task
+// by default do this...
 gulp.task('default', gulp.series('build'), () => {});