diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1ef2b6f..721a9b8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+* examples and usage instructions
+
 ### Fixed
 
 ### Changed
diff --git a/README.md b/README.md
index b7934a4..9a18d3e 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,23 @@
-A stable version of compiletest-rs
+A test runner that builds tests with rustc or cargo (or any other compiler
+with some configuration effort) and compares the output of the compiler with
+a file that you check into git. This allows you to test how your libraries
+show up to your users when the library is used wrongly and emits errors.
 
-## Magic behavior
+## Usage
+
+See [examples directory](examples) for how to use this in your own crate.
+To be able to use it with `cargo test`, you need to put
+
+```toml
+[[test]]
+name = "your_test_file"
+harness = false
+```
+
+into your `Cargo.toml`, otherwise `cargo test` will only look for `#[test]`s and
+not run your `fn main()` that actually executes `ui_test`
+
+## Implicit (and possibly surprising) behavior
 
 * Tests are run in order of their filenames (files first, then recursing into folders).
   So if you have any slow tests, prepend them with a small integral number to make them get run first, taking advantage of parallelism as much as possible (instead of waiting for the slow tests at the end).
@@ -8,7 +25,7 @@ A stable version of compiletest-rs
     * Since `cargo test` on its own runs all tests, using `cargo test -- --check` will not work on its own, but `cargo test -- --quiet` and `cargo test -- some_test_name` will work just fine, as the CLI matches.
 * if there is a `.stdin` file with the same filename as your test, it will be piped as standard input to your program.
 
-## Supported magic comment annotations
+## Supported comment annotations
 
 If your test tests for failure, you need to add a `//~` annotation where the error is happening
 to ensure that the test will always keep failing at the annotated line. These comments can take two forms:
diff --git a/examples/rustc_basic.rs b/examples/rustc_basic.rs
new file mode 100644
index 0000000..c06ec3b
--- /dev/null
+++ b/examples/rustc_basic.rs
@@ -0,0 +1,8 @@
+use ui_test::{run_tests, Config};
+
+fn main() -> ui_test::color_eyre::Result<()> {
+    // Compile all `.rs` files in the given directory (relative to your
+    // Cargo.toml) and compare their output against the corresponding
+    // `.stderr` files.
+    run_tests(Config::rustc("examples_tests/rustc_basic"))
+}
diff --git a/examples_tests/rustc_basic/hello.rs b/examples_tests/rustc_basic/hello.rs
new file mode 100644
index 0000000..09ed349
--- /dev/null
+++ b/examples_tests/rustc_basic/hello.rs
@@ -0,0 +1,4 @@
+fn main() {
+    println("hello world")
+    //~^ ERROR: expected function, found macro `println`
+}
diff --git a/examples_tests/rustc_basic/hello.stderr b/examples_tests/rustc_basic/hello.stderr
new file mode 100644
index 0000000..5f556ca
--- /dev/null
+++ b/examples_tests/rustc_basic/hello.stderr
@@ -0,0 +1,14 @@
+error[E0423]: expected function, found macro `println`
+ --> examples_tests/rustc_basic/hello.rs:2:5
+  |
+2 |     println("hello world")
+  |     ^^^^^^^ not a function
+  |
+help: use `!` to invoke the macro
+  |
+2 |     println!("hello world")
+  |            +
+
+error: aborting due to 1 previous error
+
+For more information about this error, try `rustc --explain E0423`.