diff --git a/Contributing.md b/Contributing.md
index 0cf3e0b9223..06a11973371 100644
--- a/Contributing.md
+++ b/Contributing.md
@@ -6,7 +6,8 @@ It would be really useful to have people use rustfmt on their projects and file
 issues where it does something you don't expect.
 
 A really useful thing to do that on a crate from the Rust repo. If it does
-something unexpected, file an issue; if not, make a PR to the Rust repo with the reformatted code. I hope to get the whole repo consistently rustfmt'ed and to
+something unexpected, file an issue; if not, make a PR to the Rust repo with the
+reformatted code. We hope to get the whole repo consistently rustfmt'ed and to
 replace `make tidy` with rustfmt as a medium-term goal.
 
 ### Create test cases
@@ -14,6 +15,36 @@ replace `make tidy` with rustfmt as a medium-term goal.
 Having a strong test suite for a tool like this is essential. It is very easy
 to create regressions. Any tests you can add are very much appreciated.
 
+The tests can be run with `cargo test`. This does a number of things:
+* runs the unit tests for a number of internal functions;
+* makes sure that rustfmt run on every file in `./tests/source/` is equal to its
+  associated file in `./tests/target/`;
+* runs idempotence tests on the files in `./tests/target/`. These files should
+  not be changed by rustfmt;
+* checks that rustfmt's code is not changed by running on itself. This ensures
+  that the project bootstraps.
+
+Creating a test is as easy as creating a new file in `./tests/source/` and an
+equally named one in `./tests/target/`. If it is only required that rustfmt
+leaves a piece of code unformatted, it may suffice to only create a target file.
+
+Whenever there's a discrepancy between the expected output when running tests, a
+colourised diff will be printed so that the offending line(s) can quickly be
+identified.
+
+Without explicit settings, the tests will be run using rustfmt's default
+configuration. It is possible to run a test using non-default settings by
+including configuration parameters in comments at the top of the file. For
+example: to use 3 spaces per tab, start your test with
+`// rustfmt-tab_spaces: 3`. Just remember that the comment is part of the input,
+so include in both the source and target files! It is also possible to
+explicitly specify the name of the expected output file in the target directory.
+Use `// rustfmt-target: filename.rs` for this. Finally, you can use a custom
+configuration by using the `rustfmt-config` directive. Rustfmt will then use
+that toml file located in `./tests/config/` for its configuration. Including
+`// rustfmt-config: small_tabs.toml` will run your test with the configuration
+file found at `./tests/config/small_tabs.toml`.
+
 ### Hack!
 
 Here are some [good starting issues](https://github.com/nrc/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Aeasy).
diff --git a/README.md b/README.md
index 06e8dae54f3..ecba517554f 100644
--- a/README.md
+++ b/README.md
@@ -9,9 +9,10 @@ A tool for formatting Rust code according to style guidelines.
    #[rustfmt_skip]
    #[cfg_attr(rustfmt, rustfmt_skip)]
     ```
-* When you run rustfmt use a file called rustfmt.toml to override the default
-  settings of rustfmt.
-* We create a functioning executable called `rustfmt` in the target directory
+* When you run rustfmt, place a file named rustfmt.toml in target file
+  directory or its parents to override the default settings of rustfmt.
+* After successful compilation, a `rustfmt` executable can be found in the
+  target directory.
 
 ## Installation
 
@@ -36,15 +37,16 @@ First make sure you've got Rust **1.3.0** or greater available, then:
 
 `cargo test` to run all tests.
 
-`cargo run -- filename` to run on a file, if the file includes out of line modules,
-then we reformat those too. So to run on a whole module or crate, you just need
-to run on the top file.
+`cargo run -- filename` to run on a file, if the file includes out of line
+modules, then we reformat those too. So to run on a whole module or crate, you
+just need to run on the top file.
 
-You'll probably want to specify the write mode. Currently, there are the replace,
-overwrite and display mode. The replace mode is the default and overwrites the
-original files after renaming them. In overwrite mode, rustfmt does not backup
-the source files. To print the output to stdout, use the display mode. The write
-mode can be set by passing the `--write-mode` flag on the command line.
+You'll probably want to specify the write mode. Currently, there are the
+replace, overwrite, display and coverage modes. The replace mode is the default
+and overwrites the original files after renaming them. In overwrite mode,
+rustfmt does not backup the source files. To print the output to stdout, use the
+display mode. The write mode can be set by passing the `--write-mode` flag on
+the command line.
 
 `cargo run -- filename --write-mode=display` prints the output of rustfmt to the
 screen, for example.