From 5ca7ce3f8e988fe68e9395835d94ec11f1fdec41 Mon Sep 17 00:00:00 2001
From: Jordan Suchow <suchow@post.harvard.edu>
Date: Wed, 25 Mar 2015 01:12:45 -0700
Subject: [PATCH] Update documentation

---
 CONTRIBUTING.md |  8 ++++++
 README.md       | 71 ++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 72 insertions(+), 7 deletions(-)

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).