diff --git a/README b/README
deleted file mode 100644
index f87c6c7..0000000
--- a/README
+++ /dev/null
@@ -1 +0,0 @@
-Tidx is a simple full text indexing library for Javascript
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4c49d19
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+Tidx
+====
+
+Tidx is a simple Javascript full text indexing library. Tidx is
+BSD licensed.
+
+
+basic usage
+-----------
+
+First, create a new Tidx object:
+
+ var idx = new Tidx();
+
+
+Next, add your data to the index with the index function:
+
+ idx.index(true, 1, 'Name', 'John D. Smith');
+
+
+The index function accepts four arguments: The first is a boolean
+which is if the data to be added to the index should be tokenized (that is,
+broken down into discrete searchable terms), the second is the unique
+identifier for the data (which will be returned when you search), a field
+name associated with the data (or null if you don't have a field) and the
+value you wish to add to the index. In the above example, since we've enabled
+tokenization, the value would be indexed as three terms "john", "d" and
+"smith".
+
+
+Searching your index is easy:
+
+ var results = idx.search(true, 'john');
+
+
+The search function accepts two arguments: A boolean argument of true
+if you wish your search terms to be logically conjuct (as if connected
+by AND) or false if you want your terms to be logically disjunct (as if
+connected by OR). The second argument is your search terms. The search
+function supports multiword terms when surrounded by quotes "John Smith",
+and fields can be specified by name if using a semi-colon (e.g. "name:john")
+The returned results of the search function is an array of IDs ordered by
+frequency of terms from your search.
+
+Fully functional examples of usage can be found in the examples directory.
+
+
+advanced usage
+--------------
+
+Tidx also supports chaining searches together. This is useful in instances
+where you may have multiple points of entry for a single search, and the
+results should be an aggregate of each. After your index is initialized
+and data has been added (see above), you can then search it using raw_search:
+
+ var raw_results = {};
+ var term_count = idx.raw_search('John', raw_results);
+
+
+Additional searches may then be added in the same way:
+
+ term_count += idx.raw_search('Smith', raw_results);
+
+
+Field specific, single term scans may also be included:
+
+ term_count += idx.field_scan('Name', 'David', raw_results);
+
+
+Finally, the results can be ordered and filtered:
+
+ var results = idx.order(raw_results, term_count);
+
+
+If you'd like the results of your search terms to be logically conjunct
+(as if connected by AND), specific the term count you collected from search.
+If you'd like them to be logically disjunct (as if connected by OR), specify
+a term count of zero.
diff --git a/TODO b/TODO
index c51c2c1..514893d 100644
--- a/TODO
+++ b/TODO
@@ -1,9 +1,3 @@
-Coming soon
-===========
-Better README
-Clearer function comments
-
-
Maybe one day
=============
Larger/More extensive set of test data
diff --git a/example/advanced.html b/example/advanced.html
new file mode 100644
index 0000000..b2bad05
--- /dev/null
+++ b/example/advanced.html
@@ -0,0 +1,111 @@
+
+
+ Tidx Test
+
+
+
+
+
+
+
+
+
+
+ ID |
+ Name |
+ Email |
+ City |
+ State |
+ Country |
+ Rank |
+ Description |
+
+
+
+
+
+
+
+
+
diff --git a/example/basic.html b/example/basic.html
new file mode 100644
index 0000000..13aa2bb
--- /dev/null
+++ b/example/basic.html
@@ -0,0 +1,96 @@
+
+
+ Tidx Test
+
+
+
+
+
+
+
+
+
+
+ ID |
+ Name |
+ Email |
+ City |
+ State |
+ Country |
+ Rank |
+ Description |
+
+
+
+
+
+
+
+
+
diff --git a/test.json b/example/test.json
similarity index 100%
rename from test.json
rename to example/test.json
diff --git a/test.html b/test.html
deleted file mode 100644
index ac49f98..0000000
--- a/test.html
+++ /dev/null
@@ -1,123 +0,0 @@
-
-
- Tidx Test
-
-
-
-
-
-
-
-
-
-
- ID |
- Name |
- Email |
- City |
- State |
- Country |
- Rank |
- Description |
-
-
-
-
-
-
-
-
-