improve the documentation

.npmignore

@@ -1 +1,4 @@
+/bin
+/coverage
+/doc
 /test

README.md

@@ -6,88 +6,79 @@
 [![Dependency Status][david-image]][david-url]
 [![devDependency Status][david-dev-image]][david-dev-url]
 
-This module implements experimental support for Google
-[Cloud Trace](https://cloud.google.com/cloud-trace/) for Node.js. This module is
-under development and is not suitable for production
-use at this point.
+## Overview
 
-**This module uses APIs there are undocumented and are not covered by any**
-**deprecation policy, and this may be subject to change without notice.**
+*This module is experimental, and should be used by early adopters. This module uses APIs there may be undocumented and may be subject to change without notice.*
 
-**The API this module exports is experimental and is not covered by any**
-**deprecation policy, and may be changed without notice.**
+[Cloud Trace](https://cloud.google.com/cloud-trace/) is a feature of [Google Cloud Platform](https://cloud.google.com/) that collects latency data from your applications and displays it in near real-time in the [Google Developers Console](https://console.developers.google.com/?_ga=1.258049870.576536942.1443543237). This module provides Cloud Trace support for Node.js applications.
 
-## Quick Start
+![Cloud Trace Overview](doc/images/cloud-trace-overview-page.png)
 
-Prerequisites:
-
-1. You should already be familiar with deploying Node.js apps you to the Google Cloud Platform (GCP).  See https://cloud.google.com/nodejs/ for getting started with deploying Node.js apps on GCP.
-1. You need to have created a project on GCP. You don't necessarily have to deploy your app to GCP, but traces must be attributed to a project to be viewed.
+## Prerequisites
 1. You are using / deploying-with Node.js version 0.12 or greater.
+1. You need to have created a project on GCP. You don't necessarily have to deploy your app to GCP, but traces must be attributed to a project to be viewed.
+1. [Enable the Trace API](https://console.developers.google.com/flows/enableapi?apiid=cloudtrace) for your project.
+1. (Only if you are deploying to Google Compute Engine) Your VM instances need to be created with the 'Allow API access' checkbox selected (see screenshot). If you already have VMs that were created without API access, you will additionally need to follow the instructions in the *Running elsewhere* section.
 
-[Enable the Trace API](https://console.developers.google.com/flows/enableapi?apiid=cloudtrace&_ga=1.158570170.161926390.1438300999) for your project.
-
-Install the trace agent module:
-```
-npm install --save @google/cloud-trace
-```
+![GCE API](doc/images/gce.png?raw=true)
 
-Load the module as the very first thing that gets done at the startup of your application:
+## Running on Google Cloud Platform
+1. Install the module, and save it as a dependency in your `package.json`:
 
-```javascript
-// Activate Google cloud trace agent (*must be first line of the app*)
-require('@google/cloud-trace').start();
-```
+   `npm install --save @google/cloud-trace`
+1. Ensure that the trace agent gets loaded **as the first thing** during your application's startup. You can add the following line as to load the trace agent module in your startup script. For example, if your startup script is `server.js`, add the following as the *very first line* to `server.js`:
 
-Deploy your application to Google Cloud and send some requests towards your app.
+   ``` javascript
+   // Activate Google cloud trace agent (*must be first line of the app*)
+   require('@google/cloud-trace').start();
+   ```
 
-In about 30 seconds or so, you should see trace data gathered in the Monitoring -> Traces view in your Google Cloud console:
+Deploy your application to Google Cloud and start sending some requests towards your application. In about 30 seconds or so, you should see trace data gathered in the Monitoring -> Traces view in your Google Cloud console:
 
 ![Trace List](doc/images/tracelist.png?raw=true)
+
+This is the trace list that shows a sampling of the incoming requests your application is receiving. You can click on a URI to drill down into the details. This will show you the RPCs made by your application and their associated latency:
+
 ![Trace View](doc/images/traceview.png?raw=true)
 
 Note: When you open on up the traces view under the monitoring header, you may see a warning saying traces are disabled (shown below). This refers to traces gathered by the app server responsible for hosting your application. These traces are gathered independently of the traces generated by our agent and carry less semantic information about the behavior of your application. We recommend you DO NOT click Enable trace at this time.
 
 ![Trace Warning](doc/images/butterbar.png?raw=true)
 
-If you want to run your application locally, you will need to take two additional steps:
+## Running elsewhere
+
+If you want to run your application somewhere other than Google Cloud Platform, or if you GCE VMs were created without API access, you will need to take two additional steps:
+
 1. Provide your project-number at the time you start the trace agent. Your project number can be found in the developer console by clicking gear in the upper left hand corner and looking at Project information:
-```javascript
-// Activate Google cloud trace agent (*must be first line of the app*)
-require('@google/cloud-trace').start({projectId: 'your-project-number-here'});
-```
+
+   ```javascript
+   // Activate Google cloud trace agent (*must be first line of the app*)
+   require('@google/cloud-trace').start({projectId: 'your-project-number-here'});
+   ```
 1. Provide credentials to authenticate with the Trace API.
   * Provide credentials via the environment variable GOOGLE\_APPLICATION\_CREDENTIALS. The simplest way to get a credential for this purpose is to create a service account using the Google Developers Console in the section APIs & Auth, in the sub-section Credentials. Create a service account (Create New ClientID under the OAuth heading) or choose an existing one and select Generate new JSON key. Set the environment variable GOOGLE\_APPLICATION\_CREDENTIALS to the path of the JSON file downloaded.
 
 ## Details
 
 The trace agent can do automatic tracing of the following http frameworks:
-* express v4+ 
+* express v4+
 * restify v3+ (experimental)
 * hapi v8 (experimental)
 
 We will do automatic tracing of the following kinds of RPCs performed by your application:
 * Outbound HTTP requests
-* MongoDB v2+ (experimental)
+* MongoDB v2+
 * Redis v0.12+ (experimental)
 
 We are working on expanding the types of frameworks and services we can do automatic tracing for. We are also interested in hearing your feedback on what other frameworks, or versions, you would like to see supported. This would help us prioritize support going forward.
 
 We also have an API that lets you add custom spans to the traces automatically. This can be useful if your application does sizable synchronous or asynchronous work that is not using an existing IO or RPC module.
 
-### (Optional) Enable Trace on Google Compute Engine Instances
-
-Ensure that compute instances have been created with project API access and the follow the directions above:
-
-![GCE API](doc/images/gce.png?raw=true)
-
-If your compute engine instance has already been created and was not granted project API access, follow the steps above for running locally to authenticate using a service account key.
-
 ### (Optional) Custom Tracing API
 
 Our goal is for the trace agent to automatically trace all the popular Node.js web frameworks, as well as RPC and persistence layers. However, you may still want to create custom spans to add additional details if your application does sizable on- or off-CPU work inside a request. We do provide an API to enable that.
 
-We only support custom spans inside existing top-level request-handling framework (e.g. express, hapi, etc.). 
+We only support custom spans inside existing top-level request-handling framework (e.g. express, hapi, etc.).
 
 The API for creating custom spans and modifying transaction metadata is exposed through the agent returned by requiring the module:
 
@@ -131,14 +122,8 @@ It is possible to rename the current top-level request transaction, to give it a
 Adding a label to the current top-level request transaction:
 
 ```javascript
-    agent.addTransactionLabel('label-key', 'label-value');
+  agent.addTransactionLabel('label-key', 'label-value');
 ```
-## FAQ
-* Can I view details of traces from Google Cloud REST services (such as Cloud Datastore, etc.)?
-While this does not work yet, we plan to display traces from Google Cloud services as children of the transactions in your application which invoke these services.
-
-* Where are these /_ah/health and /_ah/background spans displaying in the UI coming from?
-See: https://cloud.google.com/appengine/docs/managed-vms/config#health_checking
 
 [npm-image]: https://badge.fury.io/js/%40google%2Fcloud-trace.svg
 [npm-url]: https://npmjs.org/package/@google/cloud-trace