From ef7915fc9774fcffb793a47442e5a9e2516cfe3a Mon Sep 17 00:00:00 2001
From: Mark Wotton <mwotton@gmail.com>
Date: Sat, 6 Jun 2020 12:52:57 -0400
Subject: [PATCH] write readme

---
 README.md | 23 +++++++++++++++++++++++
 TODO.md   |  2 +-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index dd36fda..e5e2402 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,26 @@
 # roboservant
 
+Automatically fuzz your servant apis in a contextually-aware way.
+
 ![CI](https://github.com/mwotton/roboservant/workflows/CI/badge.svg)
+
+# why?
+
+Servant gives us a lot of information about what a server can do. We
+use this information to generate arbitrarily long request/response
+sessions and verify properties that should hold over them.
+
+# why not servant-quickcheck?
+
+[servant-quickcheck](https://hackage.haskell.org/package/servant-quickcheck)
+is a great package and I've learned a lot from it. Unfortunately,
+there's a lot of the state space it can't explore: modern webapps are
+full of pointer-like structures, whether they're URLs or database
+keys/uuids. servant-quickcheck demands that you be able to generate
+these without context via Arbitrary: good luck exploring an API that
+requires you to generate just the right UUID to hit non-trivial code.
+
+roboservant avoids this by using
+[quickcheck-state-machine](https://github.com/advancedtelematic/quickcheck-state-machine#readme),
+which models the dynamic state in such a way that we can use results
+of previous calls.
diff --git a/TODO.md b/TODO.md
index 4cc7fe9..b12ba3f 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,8 +1,8 @@
 DONE
 - basic setup
 - extract response types from the api
+- proper readme
 
 TODO
-- proper readme
 - some way to select a random endpoint to run from a given Server.
 - hook up quickcheck-state-machine/hedgehog