Simplify README and reorder to improve clarity (#120)

* Simplify README and re-organize

* Minor fix

README.md

@@ -1,12 +1,38 @@
-# appmetrics-dash
+# Node Application Metrics Dashboard
 
 [![Build Status](https://travis-ci.org/RuntimeTools/appmetrics-dash.svg?branch=master)](https://travis-ci.org/RuntimeTools/appmetrics-dash)
 [![codebeat badge](https://codebeat.co/badges/52b7334d-70b0-4659-9acb-b080d6413906)](https://codebeat.co/projects/github-com-runtimetools-appmetrics-dash-master)
 [![codecov.io](https://codecov.io/github/RuntimeTools/appmetrics-dash/coverage.svg?branch=master)](https://codecov.io/github/RuntimeTools/appmetrics-dash?branch=master)
 ![Apache 2](https://img.shields.io/badge/license-Apache2-blue.svg?style=flat)
 [![Homepage](https://img.shields.io/badge/homepage-Node%20Application%20Metrics-blue.svg)](https://developer.ibm.com/node/monitoring-post-mortem/application-metrics-node-js/)
 
-appmetrics-dash provides a very easy to use, web based, dashboard to show the performance metrics of your running Node.js application.  
+![Node Application Metrics Dashboard](https://developer.ibm.com/node/monitoring-post-mortem/application-metrics-node-js/) (appmetrics-dash) provides a very easy-to-use web based dashboard to show the performance metrics of your running Node.js application.
+
+If you want to add the dashboard to all HTTP servers created by your application then simply add:
+
+```js
+// Before all other 'require' statements:
+require('appmetrics-dash').attach();
+```
+to the very top of your main JavaScript source file.
+
+If you want to add the dashboard to one specific HTTP server then use:
+
+```js
+var dash = require('appmetrics-dash');
+// Other 'require' statements here
+// Create HTTP server 'myHttpServer' here
+dash.monitor({server: myHttpServer});
+```
+If you are not creating an HTTP server then use:
+
+```js
+// Before all other 'require' statements:
+require('appmetrics-dash').monitor();
+```
+
+This creates a new server for the dashboard on port 3001 by default. The path defaults to ```/appmetrics-dash```.
+E.g. http://localhost:3001/appmetrics-dash
 
 The data available on the dashboard is as follows:
 * CPU Profiling (via a separate tab)
@@ -16,7 +42,7 @@ The data available on the dashboard is as follows:
 * CPU
 * Memory
 * Heap
-* Event loop Latency
+* Event Loop Times
 * Environment
 * Other Requests
 * HTTP Outbound Requests
@@ -37,42 +63,39 @@ Our testing has shown that the performance overhead in terms of processing is mi
 
 We gathered this information by monitoring the sample application [Acme Air][3]. We used MongoDB as our datastore and used JMeter to drive load though the program.  We have performed this testing with Node.js version 6.10.3
 
-## dash = require('appmetrics-dash').monitor()
 
-This will launch the dashboard and start monitoring your application. When
-no options are specified, an http server will be created and listen on port 3001.
-The dashboard will be available at /appmetrics-dash
+## API Documentation
 
-Simple example using the express framework
+### attach(options)
 
-```js
-// This application uses express as its web server
-// for more info, see: http://expressjs.com
-var express = require('express');
+* options {Object} Options are the same as for `dash.monitor()`.
 
-var dash = require('appmetrics-dash').monitor();
+Auto-attach to all `http` servers created after this call, calling `dash.monitor(options)` for every server.
 
-// cfenv provides access to your Cloud Foundry environment
-// for more info, see: https://www.npmjs.com/package/cfenv
-var cfenv = require('cfenv');
+Simple example using attach
+```js
+var dash = require('appmetrics-dash');
+dash.attach();
 
-// create a new express server
-var app = express();
+var http = require('http');
 
-// serve the files out of ./public as our main files
-app.use(express.static(__dirname + '/public'));
+const port = 3000;
 
-// get the app environment from Cloud Foundry
-var appEnv = cfenv.getAppEnv();
+const requestHandler = (request, response) => {  
+  response.end('Hello')
+}
+
+const server = http.createServer(requestHandler);
 
-// start server on the specified port and binding host
-var server = app.listen(appEnv.port, '0.0.0.0', function() {
-	// print a message when the server starts listening
-  console.log("server starting on " + appEnv.url);
+server.listen(port, (err) => {  
+  if (err) {
+    return console.log('An error occurred', err)
+  }
+  console.log(`Server is listening on ${port}`)
 });
 ```
 
-## dash.monitor(options)
+### monitor(options)
 
 * options.url {String} Path to serve dashboard from. Optional, defaults to
   `'/appmetrics-dash'`.
@@ -97,35 +120,6 @@ var server = app.listen(appEnv.port, '0.0.0.0', function() {
 * options.title {String} Title for the dashboard.
 * options.docs {String} URL link to accompanying documentation.
 
-## dash.attach(options)
-
-* options {Object} Options are the same as for `dash.monitor()`.
-
-Auto-attach to all `http` servers created after this call, calling `dash.monitor(options)` for every server.
-
-Simple example using attach
-```js
-var dash = require('appmetrics-dash');
-dash.attach();
-
-var http = require('http');
-
-const port = 3000;
-
-const requestHandler = (request, response) => {  
-  response.end('Hello')
-}
-
-const server = http.createServer(requestHandler);
-
-server.listen(port, (err) => {  
-  if (err) {
-    return console.log('An error occurred', err)
-  }
-  console.log(`Server is listening on ${port}`)
-});
-```
-
 ## Contributing
 
 We welcome contributions. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details about the contributor licence agreement and other information. If you want to do anything more involved than a bug fix or a minor enhancement then we would recommend discussing it in an issue first before doing the work to make sure that it's likely to be accepted. We're also keen to improve test coverage and may not accept new code unless there are accompanying tests.