Merge pull request #173 from ryanseys/update-docs

Update documentation - CONTRIBUTING and README

Author: silvolu

CONTRIBUTING.md

@@ -7,30 +7,56 @@
 
 ## Testing
 
-``` sh
-# Run the tests.
-$ npm test
+### Unit tests
 
-# Run the regression tests.
-$ npm run regression-test
+To run the unit tests, simply run:
 
-# See the test coverage report.
-$ npm run cover
+``` sh
+$ npm test
 ```
 
-To run the regression tests, first create and configure a project following the [instructions on how to run gcloud-node][elsewhere]. After that, set the following environment variables:
+### Regression Tests
+
+To run the regression tests, first create and configure a project in the Google Developers Console following the [instructions on how to run gcloud-node][elsewhere]. After that, set the following environment variables:
 
 - **GCLOUD_TESTS_PROJECT_ID**: Developers Console project's ID (e.g. bamboo-shift-455)
 - **GCLOUD_TESTS_BUCKET_NAME**: The name of the bucket to use for the Cloud Storage API tests
 - **GCLOUD_TESTS_KEY**: The path to the JSON key file.
 
-Lastly, create the indexes used in the datastore regression tests using the [gcloud command-line tool][gcloudcli] and the indexes found in `regression/data/index/yaml`:
+Install the [gcloud command-line tool][gcloudcli] to your machine and use it to create the indexes used in the datastore regression tests with indexes found in `regression/data/index/yaml`:
+
+From the project's root directory:
 
 ``` sh
-# From the project's root directory:
+# Install the app component
+$ gcloud components update app
+
+# Set the default project in your env
+$ gcloud config set project $GCLOUD_TESTS_PROJECT_ID
+
+# Authenticate the gcloud tool with your account
+$ gcloud auth login
+
+# Create the indexes
 $ gcloud preview datastore create-indexes regression/data/
 ```
 
+You may now run the regression tests:
+
+``` sh
+$ npm run regression-test
+```
+
+### Test Coverage
+
+Generate the coverage report:
+
+``` sh
+$ npm run cover
+```
+
+The test coverage report will be available in `coverage/`.
+
 ## Contributor License Agreements
 
 Before we can accept your pull requests you'll need to sign a Contributor License Agreement (CLA):

README.md

@@ -2,7 +2,7 @@
 > Node idiomatic client for Google Cloud services.
 
 [![NPM Version](https://img.shields.io/npm/v/gcloud.svg)](https://www.npmjs.org/package/gcloud)
-![Travis Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-node.svg)
+[![Travis Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-node.svg)](https://travis-ci.org/GoogleCloudPlatform/gcloud-node/)
 [![Coverage Status](https://img.shields.io/coveralls/GoogleCloudPlatform/gcloud-node.svg)](https://coveralls.io/r/GoogleCloudPlatform/gcloud-node?branch=master)
 
 This client supports the following Google Cloud services:
@@ -42,25 +42,27 @@ If you are not running this client on Google Compute Engine, you need a Google D
 
 See the [Google Cloud Datastore docs](https://developers.google.com/datastore/docs/activate) for more details on how to activate Cloud Datastore for your project.
 
-See [the API documentation](https://googlecloudplatform.github.io/gcloud-node/module-datastore.html) to learn how to interact with the Cloud Datastore using this Client Library.
+See [the gcloud-node API documentation](https://googlecloudplatform.github.io/gcloud-node/#/docs/datastore) to learn how to interact with the Cloud Datastore using this Client Library.
 
 ```js
 var gcloud = require('gcloud');
 var datastore = gcloud.datastore;
 var dataset;
 
-// From Google Compute Engine
+// From Google Compute Engine:
 dataset = new datastore.Dataset({
   projectId: 'my-project',
 });
 
-// From elsewhere
+// Or from elsewhere:
 dataset = new datastore.Dataset({
   projectId: 'my-project',
-  keyFilename: '/path/to/keyfile.json' 
+  keyFilename: '/path/to/keyfile.json'
 });
 
-dataset.get(dataset.key('Product', 'Computer'), function(err, entity) {});
+dataset.get(dataset.key('Product', 'Computer'), function(err, entity) {
+  console.log(err || entity);
+});
 ```
 
 ## Google Cloud Storage
@@ -69,27 +71,35 @@ dataset.get(dataset.key('Product', 'Computer'), function(err, entity) {});
 
 You need to create a Google Cloud Storage bucket to use this client library. Follow the steps on the [Google Cloud Storage docs](https://developers.google.com/storage/docs/cloud-console#_creatingbuckets) to learn how to create a bucket.
 
-See [the API documentation](https://googlecloudplatform.github.io/gcloud-node/module-storage.html) to learn how to connect to the Cloud Storage using this Client Library.
+See [the gcloud-node API documentation](https://googlecloudplatform.github.io/gcloud-node/#/docs/storage) to learn how to connect to the Cloud Storage using this Client Library.
 
 ```js
 var gcloud = require('gcloud');
 var storage = gcloud.storage;
 var bucket;
 
-// From Google Compute Engine
+// From Google Compute Engine:
 bucket = new storage.Bucket({
   bucketName: YOUR_BUCKET_NAME
 });
 
-// From elsewhere
+// Or from elsewhere:
 bucket = new storage.Bucket({
   bucketName: YOUR_BUCKET_NAME,
   keyFilename: '/path/to/the/key.json'
 });
 
-bucket.write('filename', 'Hello World', function(err) {});
+bucket.write('demo.txt', 'Hello World', function(err) {
+  console.log(err || 'Created demo.txt');
+});
 ```
 
 ## Contributing
 
-See [CONTRIBUTING](CONTRIBUTING.md).
+Contributions to this library are always welcome and highly encouraged.
+
+See [CONTRIBUTING](CONTRIBUTING.md) for more information on how to get started.
+
+## License
+
+Apache 2.0 - See [COPYING](COPYING) for more information.