Update: Updated documentation

Author: jarrodek

README.md

@@ -1,11 +1,11 @@
+**See live example of the API console in our [demo application].**
+
 # The API Console
 
 MuleSoft's API Console is a full-fledged API documentation tool that generates mobile-friendly web documentation based on RAML (Restful API Modeling Language) documents. In addition to providing documentation, the tool provides the capability for users to try out requests on the fly.
 
 [![API Console](docs/new-console-header.png)](https://mulesoft.github.io/api-console)
 
-**See live example of the API console in our [demo application].**
-
 ## Introduction
 
 In this repository, you can find the source for a single HTML element that represents API Console.
@@ -16,6 +16,26 @@ The following sections briefly describe how to build and use the console. For mo
 
 ## Using the API console
 
+Install our CLI tool globally using `-g` if possible:
+
+```shell
+$ sudo npm install -g api-console-cli
+```
+
+Generate API console from your RAML file:
+
+```shell
+$ api-console build https://domain.com/api.raml # works with local files too
+```
+
+Preview the console:
+
+```shell
+$ api-console serve build/
+```
+
+That's all you need to build the API console for your API. Below we'll describe how to customize the console.
+
 API Console comes in two flavors.
 
 * A **standalone web-application**  

docs/passing-raml-data.md

@@ -2,7 +2,7 @@
 
 The default version of the **API console does not contain the RAML parser**. It is by design to minimize the size of the console and to optimize startup time.
 
-You can however use the console with the RAML parser setting up the build / CLI tools or by adding the dependency manually. **This document describes why the parser has been removed from the core console code and how to use the parser with new console.**
+You can use the console with the RAML parser by setting up the build / CLI tools or by adding the dependency manually. **This document describes why the parser has been removed from the core console code and how to use the parser with new console.**
 
 ## Performance of the API console
 
@@ -44,7 +44,7 @@ You can install parser and enhancer in your project by calling [bower][9] comman
 $ bower install --save advanced-rest-client/raml-json-enhance advanced-rest-client/raml-js-parser
 ```
 
-You can use `package.json` script's declaration for the same command:
+You can use `package.json` script declaration for the same command:
 
 ```json
 "scripts": {
@@ -77,59 +77,32 @@ Also check out our usage guide of the `<api-console>` element in our [element's
 <api-console></api-console>
 
 <script>
-var parser = document.querySelector('raml-js-parser');
-parser.addEventListener('api-parse-ready', function(e) {
-  var enhacer = document.querySelector('raml-json-enhance');
-  enhacer.json = e.detail.json.specification;
-});
-window.addEventListener('raml-json-enhance-ready', function(e) {
-  // The e.detail.json contains the final JavaScript object
-  var apiConsole = document.querySelector('api-console');
-  apiConsole.raml = e.detail.json;
-});
-// Assuming components are already loaded and registered
-parser.loadApi('https://domain.com/api.raml');
-</script>
-```
-
-The `json` attribute set on `raml-js-parser` element tells the parser that the output should be a JavaScript object instead of the AST.
-
-## Asynchronous environment
-
-Web components are asynchronous by nature. Importing the elements, registering them in the DOM, and finally initializing an element is done asynchronously. Therefore, you can't expect the element to work immediately after loading the page as a typical HTML element does. Consider the following example:
-
-```html
-<link rel="import" href="bower_components/raml-js-parser/raml-js-parser.html">
-<raml-js-parser json></raml-js-parser>
-<script>
-var parser = document.querySelector('raml-js-parser');
-parser.loadApi(apiFileUrl);
-</script>
-```
-
-Running this code as the page loads throws a `TypeError` with the message: `parser.loadApi is not a function`.
-
-At the time of execution of this script block, the browser knows nothing about the `raml-js-parser` element. At this time, the element is an instance of `HTMLUnknownElement`. You can read more about custom elements registration in our [starters guide to web components][2].
-
-The browser has to import the source of the element first, and then the Polymer library has to register custom HTML element called `raml-js-parser`.
-
-To run the code properly you have to listen for the `WebComponentsReady` event. It's fired when the elements are ready to use.
-
-```html
-<link rel="import" href="bower_components/raml-js-parser/raml-js-parser.html">
-<raml-js-parser json></raml-js-parser>
-<script>
-function init() {
-  var parser = document.querySelector('raml-js-parser');
-  parser.loadApi(apiFileUrl);
+var MyAPiApp = {
+  init: function() {
+    var parser = document.querySelector('raml-js-parser');
+    parser.addEventListener('api-parse-ready', MyAPiApp._ramlReady);
+    parser.loadApi('https://domain.com/api.raml');
+    window.addEventListener('raml-json-enhance-ready', MyAPiApp._jsonReady);
+  },
+
+  _ramlReady: function(e) {
+    var enhacer = document.querySelector('raml-json-enhance');
+    enhacer.json = e.detail.json.specification;
+  },
+
+  _jsonReady: function(e) {
+    // The e.detail.json contains the final JavaScript object
+    var apiConsole = document.querySelector('api-console');
+    apiConsole.raml = e.detail.json;
+  }
 };
-window.addEventListener('WebComponentsReady', init);
+window.addEventListener('WebComponentsReady', MyAPiApp.init);
 </script>
 ```
 
-Because of differences between `v0` and `v1` spec of custom elements and fallback provided by the Polymer library read [our guide](api-console-element.md) of how to properly listen for the elements registration event.
+The `json` attribute set on `raml-js-parser` element tells the parser that the output should be a JavaScript object instead of the AST.
 
-### Setting RAML data as an HTML attribute
+### Setting RAML data as a HTML attribute
 
 The basic method for determining what API Console displays is to use the `raml` attribute. The attribute accepts the JavaScript object produced by the parser and the enhancer described above.
 

docs/web-components.md

@@ -1,4 +1,4 @@
-# Starting with web components
+# Getting started with web components
 
 Web Components is relatively new specification for the web platform and therefore it is understandable that not all developers know how to use them.
 
@@ -51,21 +51,19 @@ When the element is already registered and it is instantiated and inserted into
 
 **adoptedCallback** is called when the custom element has been moved into a new document.
 
-## So when an element is ready to be used?
+## So when an element is ready to use?
 
-If you include definition of your element into the source of the web page and register it before application code runs then you can use the element's API right away. When using API console build tools one of the options do exactly that. At the time when browser parser runs JavaScript code of the application (when it suppose to parse RAML or set JavaScript object on the console) all elements are already registered and full API is available.
-
-However, even when using our build tools, you can include console elements definition from other file to defer the source code download. In this case you should call element's API differently.
+If you include definition of your element into the source of the web page and register it before application code runs then you can use the element's API right away. When using API console build tools the default build is a standalone application that contains all dependencies in index page source. At the time when browser parser runs JavaScript code of the application (when it suppose to parse RAML data or set JavaScript object on the console) all elements are already registered and full API is available.
 
+It is possible to include console's sources from an external file (to reduce initial load time, for example). In this
+case web components are not yet registered when running application's JavaScript code.
 Properties can be set whether the element is `HTMLUnknownElement` or defined element. Once the element is upgraded created the `attributeChangedCallback` is called for each set attribute.
 
-Calling element's API methods exposed to external environment (outside shadow DOM) the methods will be `undefined` for `HTMLUnknownElement`. Therefore the application has to wait until the element is upgraded.
-
-In the API console that still works on so called `v0` specification of the web components the application would wait until `WebComponentsReady` event is fired (it is provided by the Polymer library if not supported natively). After the event is fired all element should be registered and upgraded (if already in the DOM).
+Calling element's API methods exposed to external environment (outside shadow DOM) will result with error because at the time the element hasn't been upgraded. Application must wait until `WebComponentsReady` event is fired by the polyfill library. After that event all components are upgraded and ready to use.
 
 ## Creating a web component
 
-There are already a lot of nice tutorials about creating web components so it's redundant. Personally I can suggest Eric Bidelman's [Custom Elements v1: Reusable Web Components](https://developers.google.com/web/fundamentals/architecture/building-components/customelements). It is a good introduction into web components and explanation how to register and use them.
+There are already a lot of good tutorials about creating web components so it's redundant. Personally I can suggest Eric Bidelman's [Custom Elements v1: Reusable Web Components](https://developers.google.com/web/fundamentals/architecture/building-components/customelements). It is a good introduction to web components and explanation how to register and use them.
 
 If you have any question use our issue tracker to contact me. I'll be happy to help you to use the API console.