diff --git a/README.md b/README.md
index ed6b496c..f582efd7 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # markdownlint
 
-> A Node.js style checker/lint tool for Markdown files.
+> A Node.js style checker and lint tool for Markdown files.
 
 ## Install
 
@@ -11,32 +11,134 @@ npm install markdownlint --save-dev
 ## Overview
 
 The [Markdown](http://en.wikipedia.org/wiki/Markdown) markup language is
-designed to be easy to read, write, and work with. The language has succeeded,
-but its flexibility is both a benefit and a drawback. Many stylistic decisions
-are left to the author, so formatting can be inconsistent. Some constructs
-don't work well in all parsers and should be avoided.
+designed to be easy to read, write, and understand. It succeeds - and its
+flexibility is both a benefit and a drawback. Many styles are possible, so
+formatting can be inconsistent. Some constructs don't work well in all
+parsers and should be avoided.
 
 `markdownlint` is a [static analysis](http://en.wikipedia.org/wiki/Static_program_analysis)
 tool for [Node.js](https://nodejs.org/) and [io.js](https://iojs.org/) with a
-library of rules to enforce standards and correctness for Markdown files. It
-was inspired by - and heavily influenced by - Mark Harrison's [markdownlint
-for Ruby](https://github.com/mivok/markdownlint): the rules, rule
-documentation, and tests for `markdownlint` come directly from that project.
+library of rules to enforce standards and consistency for Markdown files. It
+was inspired by - and heavily influenced by - Mark Harrison's
+[markdownlint](https://github.com/mivok/markdownlint) for
+[Ruby](https://www.ruby-lang.org/). The rules, rule documentation, and test
+cases come directly from that project.
 
-> Aside: If you need a Ruby implementation or CLI, please consider
-> [mdl](https://rubygems.org/gems/mdl). If you work with both platforms, most
-> of what you know can be applied directly.
+> If you need a Ruby implementation or a [CLI](http://en.wikipedia.org/wiki/Command-line_interface),
+> please consider the [mdl](https://rubygems.org/gems/mdl) gem.
 
 ## Rules
 
-See [Rules.md](doc/Rules.md)
+* MD001 - Header levels should only increment by one level at a time
+* MD002 - First header should be a h1 header
+* MD003 - Header style
+* MD004 - Unordered list style
+* MD005 - Inconsistent indentation for list items at the same level
+* MD006 - Consider starting bulleted lists at the beginning of the line
+* MD007 - Unordered list indentation
+* MD009 - Trailing spaces
+* MD010 - Hard tabs
+* MD011 - Reversed link syntax
+* MD012 - Multiple consecutive blank lines
+* MD013 - Line length
+* MD014 - Dollar signs used before commands without showing output
+* MD018 - No space after hash on atx style header
+* MD019 - Multiple spaces after hash on atx style header
+* MD020 - No space inside hashes on closed atx style header
+* MD021 - Multiple spaces inside hashes on closed atx style header
+* MD022 - Headers should be surrounded by blank lines
+* MD023 - Headers must start at the beginning of the line
+* MD024 - Multiple headers with the same content
+* MD025 - Multiple top level headers in the same document
+* MD026 - Trailing punctuation in header
+* MD027 - Multiple spaces after blockquote symbol
+* MD028 - Blank line inside blockquote
+* MD029 - Ordered list item prefix
+* MD030 - Spaces after list markers
+* MD031 - Fenced code blocks should be surrounded by blank lines
+* MD032 - Lists should be surrounded by blank lines
+
+See [Rules.md](doc/Rules.md) for more details.
 
 ## Usage
 
-...
+Invoke `markdownlint` and use the `result` object's `toString` method:
 
 ```js
-...
+var markdownlint = require("../lib/markdownlint");
+
+var options = {
+  "files": [ "good.md", "bad.md" ]
+};
+
+markdownlint(options, function callback(err, result) {
+  if (!err) {
+    console.log(result.toString());
+  }
+});
+```
+
+Outputs:
+
+```text
+bad.md: 3: MD010 Hard tabs
+bad.md: 1: MD018 No space after hash on atx style header
+bad.md: 3: MD018 No space after hash on atx style header
+```
+
+Or examine the `result` object directly:
+
+```js
+markdownlint(options, function callback(err, result) {
+  if (!err) {
+    console.dir(result, { "colors": true });
+  }
+});
+```
+
+Outputs:
+
+```json
+{
+  'good.md': {},
+  'bad.md': {
+    MD010: [ 3 ],
+    MD018: [ 1, 3 ]
+  }
+}
+```
+
+Integration with the [gulp](http://gulpjs.com/) build system is straightforward:
+
+```js
+var gulp = require("gulp");
+var through2 = require("through2");
+var markdownlint = require("../lib/markdownlint");
+
+gulp.task("markdownlint", function task() {
+  return gulp.src("*.md", { "read": false })
+    .pipe(through2.obj(function obj(file, enc, next) {
+      markdownlint(
+        { "files": [ file.relative ] },
+        function callback(err, result) {
+          var resultString = (result || "").toString();
+          if (resultString) {
+            console.log(resultString);
+          }
+          next(err, file);
+        });
+    }));
+});
+```
+
+Outputs:
+
+```text
+[00:00:00] Starting 'markdownlint'...
+bad.md: 3: MD010 Hard tabs
+bad.md: 1: MD018 No space after hash on atx style header
+bad.md: 3: MD018 No space after hash on atx style header
+[00:00:00] Finished 'markdownlint' after 10 ms
 ```
 
 ## Release History
diff --git a/lib/markdownlint.js b/lib/markdownlint.js
index fb5507cf..2ef39dbb 100644
--- a/lib/markdownlint.js
+++ b/lib/markdownlint.js
@@ -8,6 +8,8 @@ var shared = require("./shared");
 var ruleToDescription = {};
 rules.forEach(function forRule(rule) {
   ruleToDescription[rule.name] = rule.desc;
+  // The following is useful for updating README.md
+  // console.log("* " + rule.name + " - " + rule.desc);
 });
 
 function Results() { }
diff --git a/package.json b/package.json
index 93adf24b..49d9b1a5 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "markdownlint",
   "version": "0.0.1",
-  "description": "A linting tool for Markdown files",
+  "description": "A Node.js style checker and lint tool for Markdown files.",
   "main": "lib/markdownlint.js",
   "author": "David Anson (http://dlaa.me/)",
   "license": "MIT",