diff --git a/README.md b/README.md
index c86b3c70..e180ad5a 100644
--- a/README.md
+++ b/README.md
@@ -76,23 +76,32 @@ $ npm install ioredis
 ## Basic Usage
 
 ```javascript
-var Redis = require("ioredis");
-var redis = new Redis();
+const Redis = require("ioredis");
+const redis = new Redis(); // uses defaults unless given configuration object
 
-redis.set("foo", "bar");
+// ioredis supports all Redis commands:
+redis.set("foo", "bar"); // returns promise which resolves to string, "OK"
+
+// the format is: redis[SOME_REDIS_COMMAND_IN_LOWERCASE](ARGUMENTS_ARE_JOINED_INTO_COMMAND_STRING)
+// the js: ` redis.set("mykey", "Hello") ` is equivalent to the cli: ` redis> SET mykey "Hello" `
+
+// ioredis supports the node.js callback style
 redis.get("foo", function(err, result) {
-  console.log(result);
+  if (err) {
+    console.error(err);
+  } else {
+    console.log(result); // Promise resolves to "bar"
+  }
 });
-redis.del("foo");
 
-// Or using a promise if the last argument isn't a function
+// Or ioredis returns a promise if the last argument isn't a function
 redis.get("foo").then(function(result) {
-  console.log(result);
+  console.log(result); // Prints "bar"
 });
 
-// Arguments to commands are flattened, so the following are the same:
-redis.sadd("set", 1, 3, 5, 7);
-redis.sadd("set", [1, 3, 5, 7]);
+// Most responses are strings, or arrays of strings
+redis.zadd("sortedSet", 1, "one", 2, "dos", 4, "quatro", 3, "three")
+redis.zrange("sortedSet", 0, 2, "WITHSCORES").then(res => console.log(res)); // Promise resolves to ["one", "1", "dos", "2", "three", "3"] as if the command was ` redis> ZRANGE sortedSet 0 2 WITHSCORES `
 
 // All arguments are passed directly to the redis server:
 redis.set("key", 100, "EX", 10);
diff --git a/examples/basic_operations.js b/examples/basic_operations.js
index e69cac87..ec3876fb 100644
--- a/examples/basic_operations.js
+++ b/examples/basic_operations.js
@@ -1,30 +1,47 @@
-"use strict";
-
-var Redis = require("ioredis");
-var redis = new Redis();
+const Redis = require("ioredis");
+const redis = new Redis({
+  port: process.env.redisPort,
+  host: process.env.redisEndpoint,
+  password: process.env.redisPW
+});
 
 // ioredis supports all Redis commands:
-redis.set("foo", "bar");
+redis.set("foo", "bar"); // returns promise which resolves to string, "OK"
+
+// the format is: redis[SOME_REDIS_COMMAND_IN_LOWERCASE](ARGUMENTS_ARE_JOINED_INTO_COMMAND_STRING)
+// the js: ` redis.set("mykey", "Hello") ` is equivalent to the cli: ` redis> SET mykey "Hello" `
+
+// ioredis supports the node.js callback style
 redis.get("foo", function(err, result) {
   if (err) {
     console.error(err);
   } else {
-    console.log(result);
+    console.log(result); // Promise resolves to "bar"
   }
 });
-redis.del("foo");
 
-// Or using a promise if the last argument isn't a function
+// Or ioredis returns a promise if the last argument isn't a function
 redis.get("foo").then(function(result) {
   console.log(result);
 });
 
+redis.del("foo");
+
 // Arguments to commands are flattened, so the following are the same:
 redis.sadd("set", 1, 3, 5, 7);
 redis.sadd("set", [1, 3, 5, 7]);
+redis.spop("set"); // Promise resolves to "5" or another item in the set
+
+// Most responses are strings, or arrays of strings
+redis.zadd("sortedSet", 1, "one", 2, "dos", 4, "quatro", 3, "three")
+redis.zrange("sortedSet", 0, 2, "WITHSCORES").then(res => console.log(res)); // Promise resolves to ["one", "1", "dos", "2", "three", "3"] as if the command was ` redis> ZRANGE sortedSet 0 2 WITHSCORES `
+
+// Some responses have transformers to JS values
+redis.hset("myhash", "field1", "Hello");
+redis.hgetall("myhash").then(res => console.log(res)); // Promise resolves to Object {field1: "Hello"} rather than a string, or array of strings
 
 // All arguments are passed directly to the redis server:
-redis.set("key", 100, "EX", 10);
+redis.set("key", 100, "EX", 10); // set's key to value 100 and expires it after 10 seconds
 
 // Change the server configuration
 redis.config("set", "notify-keyspace-events", "KEA");