diff --git a/README b/README
deleted file mode 100644
index 4ccea4d9..00000000
--- a/README
+++ /dev/null
@@ -1 +0,0 @@
-A Restful front controller built on Hack.
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..e84ad30e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,93 @@
+A Restful front controller built on Hack.
+
+Below is an overview of how the refactored code will hopefully turn out.
+
+# Terminology
+
+## Verb
+
+HTTP request methods. Possible values: GET, POST, PUT, DELETE. Please see
+http://rest.blueoxen.net/cgi-bin/wiki.pl?MinimumMethods. In sum:
+
+GET: Read only.
+PUT: Replace data on server.
+DELETE: Remove data from server.
+POST: Some form of update.
+
+FIXME Note: not all clients support PUT and DELETE. Therefore, we need a
+workaround. I will implement two fixes:
+
+1. X-HTTP-Method-Override header.
+2. Get parameter (ie, in the query string). This will be more useful for web forms.
+
+## Resource
+
+A Resource is a single URL. Each Resource can be addressed with the four verbs,
+though does not necesarily support all of them. There are a few different ways
+of passing parameters:
+
+1. URL parameter. For example, you can set up your application so that
+/articles/my_title/ will hand off to the article resource with a parameter of
+my_title. The idea here is to avoid the regexs present in most other
+frameworks and provide a uniform interface for all parameters.
+
+2. Get parameter, ie query string.
+
+3. Post parameter, ie content body. This is *not* available for GET requests.
+However, it *is* available for PUT and DELETE.
+
+4. Headers, including cookies.
+
+### ResourceName
+
+As a side point to the URL parameter mentioned above: let us say you have
+multiple resources like /articles/my_title/ and /articles/other_title/. You
+clearly do not want to write code twice to process these requests. Instead,
+convert the article name into a URL parameter and then articles will have its
+own ResourceName.
+
+## RawRequest
+
+The parsed data sent from the client. Has, for example, GET and POST
+parameters, not QUERY_STRING and CONTENT_BODY.
+
+## Request
+
+Request is actually a **type class** for parsing a RawRequest. This allows
+putting all form handling code and the like into a single place. Your handler
+code (see below) need only deal with your data type.
+
+## Representation
+
+Some method of showing data to the client. These are identified by MIME types.
+For the most part, you should be using hierarchichal data (see Data.Object).
+There are some exceptions, such as:
+
+* HTML for non-Ajax clients (search engines, old browsers).
+* Atom/RSS feeds.
+* Sitemaps.
+
+Whenever possible, use Data.Object, as this will automatically handle some
+basic representations (JSON, JSONP, Yaml, XML, undecorated HTML).
+
+## Response
+
+Contains basic HTTP response information and something which can be represented
+in different ways.
+
+## Handler
+
+There is a single Handler for each combination of ResourceName and Verb. A
+Handler takes some instance of Request and returns a Response.
+
+# Static files
+
+All static files should go under the /static/ path. A typical application will
+probably have a Javascript file in there which deals directly with the entire
+Restful API.
+
+# Non-Ajax clients
+
+Search engines nad older clients should not be ignored. However, it is quite
+tedious to write view code twice. Hopefully, in the future there will be a view
+component to this framework which can automate some of that process.