readme

README.md

@@ -1,6 +1,15 @@
 # ExExample
 
-**TODO: Add description**
+Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
+and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
+be found at <https://hexdocs.pm/ex_example>.
+
+`ExExample` aims to provide an example-driven test framework for Elixir applications.
+
+As opposed to regular unit tests, examples are supposed to be executed from within the REPL.
+
+Examples serve both as a unit test, but also as a tool to discover, learn, and interact with a live
+system such as Elixir applications.
 
 ## Installation
 
@@ -15,7 +24,28 @@ def deps do
 end
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at <https://hexdocs.pm/ex_example>.
+## Your First Example
+
+To get started, create a new module in the `lib/` folder of your Elixir application and add an example.
+
+```elixir
+defmodule MyExamples do
+  use ExExample
+  defexample read_data() do
+    1..1000 |> Enum.shuffle() |> Enum.take(10)
+  end
+end
+```
+
+In a running REPL with your application loaded, you can execute this example using `MyExamples.read_data()`.
+The example will be executed once, and the cached result will be returned the next time around.
+
+## Caching
+
+In a REPL session it's not uncommon to recompile your code (e.g., using `recompile()`). This changes
+the semantics of your examples.
+
+To avoid working with stale outputs, `ExExample` only returns the cached version of your example
+if the code it depends on, or the example itself, have not been changed.
 
+When the code changes, the example is executed again.