diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d1e94ae94..db99d113e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1 +1,9 @@
 Work on proselint happens over at http://github.com/suchow/proselint. To contribute, create a new branch off of master and then open a pull request. You code should run cleanly through pep8 and pep257 linters. Comments, bug reports, and other feedback can be provided through GitHub issues.
+
+To create a new check:
+0. Pick a name for your check, e.g., `misc.abc_checkname`.
+1. Create a copy of `checks/inprogress/example_check.py`, renaming it to `abc_checkname.py` and placing it in `checks/misc/`.
+2. Edit your check.
+3. Create a new test file `test_abc_checkname.py` and place it in `tests`.
+4. Run the test suite using `nosetests`.
+5. Submit a pull request to suchow/proselint.
diff --git a/README.md b/README.md
index 8c147f661..22afc5700 100644
--- a/README.md
+++ b/README.md
@@ -2,12 +2,69 @@
 
 `proselint` places the world's greatest writers and editors by your side, where they whisper suggestions on how to improve your prose.
 
+### Installation
+
 To get this up and running as a command line utility, run `python setup.py develop` from inside the root directory.
 
-## Creating a new check
-0. Pick a name for your check, e.g., `abc_checkname`.
-1. Create a copy of `checks/inprogress/example_check.py`, renaming it `abc_checkname.py` and placing it in `checks/inprogress/`.
-2. Edit your check.
-3. Create a new test file `test_abc_checkname.py` and place it in `tests`.
-4. Run the test suite using `nosetests`.
-5. Submit a pull request to suchow/proselint.
+```
+$ python setup.py develop
+```
+
+### API
+
+```js
+proselint --json
+```
+
+The output is a JSON structure with the following format:
+
+```js
+{
+    // Type of check that output this suggestion
+    check: "wallace.uncomparables",
+
+    // Level of importance
+    // "suggestion", "warning", "error"
+    level: "warning",
+
+    // Line where the error occurred.
+    line: 0,
+
+    // Column where the error occurred.
+    column: 10,
+
+    // Index in the text
+    start: 10,
+
+    // Size of the section in the text
+    end: 2,
+
+    // Message to describe the suggestion
+    message: "Comparison of an uncomparable: 'very unique' is not comparable.",
+
+    // Replacements suggestion
+    replacements: [
+        {
+            value: ""
+        }
+    ]
+}
+```
+
+### Checks
+
+You can disable any of the checks by modifying `.proselintrc`.
+
+| ID    | Description     |
+| ----- | --------------- |
+| `passive` | Checks for passive voice |
+| `lexical-illusion` | Checks for lexical illusions – cases where a word is repeated. |
+| `so` | Checks for `so` at the beginning of the sentence. |
+| `adverbs` | Checks for adverbs that can weaken meaning: really, very, extremely, etc. |
+| `readibility` | Checks for readibility of sentences. |
+| `simplicity` | Checks for simpler expressions |
+| `weasel` | Checks for "weasel words." |
+
+### Contributing
+
+We'd love to accept your patches and contributions to improve `proselint`. Learn more about how to contribute in [CONTRIBUTING.md](./CONTRIBUTING.md).