diff --git a/README.md b/README.md
index bca9c93..9e0295a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,15 @@
 # retry
 Retry a command until the command succeeds.
 
+Retry captures stdin into memory as the data is passed to the repeated
+command, and this captured stdin is then replayed should the command be
+repeated. This makes it possible to embed the retry tool into shell pipelines.
+
+Retry captures stdout into memory, and if the command was successful stdout
+is passed on to stdout as normal, while if the command was repeated stdout is
+passed to stderr instead. This ensures that output is passed to stdout once
+and once only.
+
 # example
 ```
 ~$ retry --until=success false
@@ -9,3 +18,9 @@ retry: 'false' returned 1, backing off for 10 seconds and trying again...
 retry: 'false' returned 1, backing off for 10 seconds and trying again...
 ^C
 ```
+
+# more complex example
+```
+~$ retry curl --fail http://localhost/entities | jq ... | retry curl --fail -X POST http://localhost/entities
+```
+