README.rdoc in state_machine-0.2.0 vs README.rdoc in state_machine-0.2.1

@@ -1,8 +1,9 @@
 == state_machine
 
-+state_machine+ adds support for creating state machines for attributes within a model.
++state_machine+ adds support for creating state machines for attributes within
+a model.
 
 == Resources
 
 API
 
@@ -26,19 +27,25 @@
 the status of a record is kept by creating multiple boolean columns in the table
 and deciding how to behave based on the values in those columns.  This can become
 cumbersome and difficult to maintain when the complexity of your models starts to
 increase.
 
-+state_machine+ simplifies this design by introducing the various parts of a state
-machine, including states, events, and transitions.  However, its api is designed
-to be similar to ActiveRecord in terms of validations and callbacks, making it
-so simple you don't even need to know what a state machine is :)
++state_machine+ simplifies this design by introducing the various parts of a real
+state machine, including states, events, and transitions.  However, the api is
+designed to be similar to ActiveRecord in terms of validations and callbacks,
+making it so simple you don't even need to know what a state machine is :)
 
 == Usage
 
 === Example
 
+Below is an example of many of the features offered by this plugin, including
+* Initial states
+* State callbacks
+* Event callbacks
+* Conditional transitions
+
   class Vehicle < ActiveRecord::Base
     state_machine :state, :initial => 'idling' do
       before_exit   'parked', :put_on_seatbelt
       after_enter   'parked', Proc.new {|vehicle| vehicle.update_attribute(:seatbelt_on, false)}
       
@@ -72,10 +79,34 @@
       
       event :repair, :after => :fix! do
         transition :to => 'parked', :from => 'stalled', :if => :auto_shop_busy?
       end
     end
+    
+    def tow!
+    end
+    
+    def fix!
+    end
+    
+    def auto_shop_busy?
+      false
+    end
   end
+
+Using the above model as an example, you can interact with the state machine
+like so:
+
+  vehicle = Vehicle.create    # => #<Vehicle id: 1, seatbelt_on: false, state: "parked">
+  vehicle.ignite              # => true
+  vehicle                     # => #<Vehicle id: 1, seatbelt_on: true, state: "idling">
+  vehicle.shift_up            # => true
+  vehicle                     # => #<Vehicle id: 1, seatbelt_on: true, state: "first_gear">
+  vehicle.shift_up            # => true
+  vehicle                     # => #<Vehicle id: 1, seatbelt_on: true, state: "second_gear">
+  
+  # The bang (!) operator can raise exceptions if the event fails
+  vehicle.park!               # => PluginAWeek::StateMachine::InvalidTransition: Cannot transition via :park from "second_gear"
 
 == Tools
 
 Jean Bovet - {Visual Automata Simulator}[http://www.cs.usfca.edu/~jbovet/vas.html].
 This is a great tool for "simulating, visualizing and transforming finite state