README.md in speaky_csv-0.0.2 vs README.md in speaky_csv-0.0.3

@@ -1,11 +1,53 @@
 # Speaky CSV
 
-CSV exporting and importing for ActiveRecord and ActiveModel records.
+CSV imports and exports for ActiveRecord.
 
-Speaky lets the format of csv files to be customized, but it does
-require certain conventions to be followed. At a high level, the csv
+## For example
+
+Lets say there exists a User class:
+
+    # in app/models/user.rb
+    class User < ActiveRecord::Base
+      ...
+    end
+
+Speaky can be used to import and export user records. The definition of
+the csv format could look like this:
+
+    # in app/csv/user_csv.rb
+    class UserCsv < SpeakyCsv::Base
+      define_csv_fields do |config|
+        config.field :id, :email, :roles
+      end
+    end
+
+Now lets import some user records. An import csv will always have an
+initial header row, with each following row representing a user record.
+lets import the following csv file (whitespace for clarity):
+
+    # my_import.csv
+    id, email,              roles
+    22, [e-mail], admin
+      , [e-mail],   user
+
+This file can be imported like this:
+
+    File.open "my_import.csv", "r" do |io|
+      importer = UserCsv.new.active_record_importer io, User
+      importer.each { |user| user.save }
+    end
+
+## Custom CSV formats
+
+Speaky
+
+
+Speaky allows customization of csv files to a degree, but some
+conventions need to be followed.
+
+At a high level, the csv
 ends up looking similar to the way active record data gets serialized
 into form parameters which will be familiar to many rails developers.
 The advantage of this approach is that associated records be imported
 and exported.
 
@@ -44,10 +86,16 @@
 Once the format is defined records can be exported like this:
 
     $ exporter = UserCsv.new.exporter(User.all)
     $ File.open('users.csv', 'w') { |io| exporter.each { |row| io.write row } }
 
+TODO:
+
+* describe importing to attribute list
+* describe importing to to active records
+* describe how to transform with an enumerator
+
 ## Recommendations
 
 * Add `id` and `_destroy` fields for active record models
 * For associations, use `nested_attributes_for` and add `id` and
   `_destroy` fields
@@ -60,9 +108,12 @@
 * [x] export validations
 * [x] attr import validations
 * [x] active record import validations
 * [ ] `has_one` associations
 * [ ] required fields (make `lock_version` required for example)
+* [ ] transformations for values via accessors on class
+* [ ] public stable api for csv format definition
+* [ ] assign attrs one at a time so they don't all fail together
 
 ## Contributing
 
 1. Fork it ( http://github.com/ajh/speaky_csv/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)