README.md in simple_states-0.0.1 vs README.md in simple_states-0.0.2

@@ -1,5 +1,68 @@
 # simple\_states
 
-A super-slim (~200 loc) statemachine-like support library focussed on use in Travis CI.
+A super-slim (~200 loc) statemachine-like support library focussed on use in
+Travis CI.
 
-More docs coming soon, checkout the tests.
+## Usage
+
+Define states and events like this:
+
+    class Foo
+      include SimpleStates
+
+      states :created, :started, :finished
+
+      event :start,  :from => :created, :to => :started,  :if => :startable?
+      event :finish, :to => :finished, :after => :cleanup
+
+      attr_accessor :state
+
+      def start
+        # start foo
+      end
+    end
+
+Including the SimpleStates module to your class is currently required. We'll add
+hooks for ActiveRecord etc later.
+
+SimpleStates expects your model to support attribute accessors for `:state`.
+
+Event options have the following well-known meanings:
+
+    :from   # valid states to transition from
+    :to     # target state to transition to
+    :if     # only proceed if the given method returns true
+    :unless # only proceed if the given method returns false
+    :before # run the given method before running `super` and setting the new state
+    :after  # run the given method at the very end
+
+All of these options except for `:to` can be given as a single symbol or string or
+as an Array of symbols or strings.
+
+Calling `event` will effectively add methods to a proxy module which is
+included to the singleton class of your class' instances. E.g. declaring `event
+:start` in the example above will add a method `start` to a module included to
+the singleton class of instances of `Foo`.
+
+This method will
+
+1. check if `:if`/`:except` conditions apply (if given) and just return from the method otherwise
+2. check if the object currently is in a valid `:from` state (if given) and raise an exception otherwise
+3. run `:before` callbacks (if given)
+4. call `super` if Foo defines the current method (i.e. call `start` but not `finish` in the example above)
+5. add the object's current state to its `past_states` history
+6. set the object's `state` to the target state given as `:to`
+7. set the object's `[state]_at` attribute to `Time.now` if the object defines a writer for it
+8. run `:after` callbacks (if given)
+
+You can define options for all events like so:
+
+    event :finish, :to => :finished, :after => :cleanup
+    event :all, :after => :notify
+
+This will call :cleanup first and then :notify on :finish.
+
+If no target state was given for an event then SimpleStates will try to derive
+it from the states list. I.e. for an event `start` it will check the states
+list for a state `started` and use it. If it can not find a target state this
+way then it will raise an exception.