Gates.md in flipper-0.11.0.beta8

- old
+ new

@@ -13,27 +13,31 @@
 flipper[:stats].enabled? # check
 ```
 
 ## 2. Group
 
-Turn on feature based on value of block. Super flexible way to turn on a feature for multiple things (users, people, accounts, etc.)
+Turn on feature based on the return value of block. Super flexible way to turn on a feature for multiple things (users, people, accounts, etc.) as long as the thing returns true when passed to the block. 
 
 ```ruby
+# this registers a group
 Flipper.register(:admins) do |actor|
   actor.respond_to?(:admin?) && actor.admin?
 end
 
 flipper = Flipper.new(adapter)
 
-flipper[:stats].enable flipper.group(:admins) # turn on the stats feature for admins
+flipper[:stats].enable flipper.group(:admins) # This registers a stats feature and turns it on for admins (which is anything that returns true from the registered block).
 flipper[:stats].disable flipper.group(:admins) # turn off the stats feature for admins
 
 person = Person.find(params[:id])
 flipper[:stats].enabled? person # check if enabled, returns true if person.admin? is true
 
-# you can also use shortcut methods
+# you can also use shortcut methods. This also registers a stats feature and turns it on for admins.
 flipper.enable_group :stats, :admins
+person = Person.find(params[:id])
+flipper[:stats].enabled? person # same as above. check if enabled, returns true if person.admin? is true
+
 flipper.disable_group :stats, :admins
 flipper[:stats].enable_group :admins
 flipper[:stats].disable_group :admins
 ```
 
@@ -48,21 +52,31 @@
 
 ```
 flipper[:stats].enable flipper.group(:admins)
 ```
 
-- The above enables the stats feature to any object that returns true from the :admins proc.
+- The above enables the stats feature to any object that returns true from the `:admins` proc.
 
 ```
 person = Person.find(params[:id])
 flipper[:stats].enabled? person # check if person is enabled, returns true if person.admin? is true
 ```
 
 When the `person` object is passed to the `enabled?` method, it is then passed into the proc. If the proc returns true, the entire statement returns true and so `flipper[:stats].enabled? person` returns true. Whatever logic follows this conditional check is then executed.
 
 There is no requirement that the thing yielded to the block be a user model or whatever. It can be anything you want, therefore it is a good idea to check that the thing passed into the group block actually responds to what you are trying to do in the `register` proc.
 
+In your application code, you can do something like this now:
+
+```
+if flipper[:stats].enabled?(some_admin)
+  # do thing...
+else
+  raise "Your are not authorized to view this page"
+end 
+```
+
 ## 3. Individual Actor
 
 Turn feature on for individual thing. Think enable feature for someone to test or for a buddy. The only requirement for an individual actor is that it must respond to `flipper_id`.
 
 ```ruby
@@ -135,16 +149,17 @@
 flipper = Flipper.new(adapter)
 
 # get percentage of time instance set to 5
 percentage = flipper.time(5)
 
-# turn on logging for 5 percent of the time
-# could be on during one request and off the next
+# Register a feature called logging and turn it on for 5 percent of the time.
+# This could be on during one request and off the next
 # could even be on first time in request and off second time
 flipper[:logging].enable percentage
+flipper[:logging].enabled? # this will return true 5% of the time.
 
 # you can also use shortcut methods
-flipper.enable_percentage_of_time :search, 5
+flipper.enable_percentage_of_time :search, 5 # registers a feature called "enable_percentage_of_time" and enables it 5% of the time
 flipper.disable_percentage_of_time :search # sets to 0
 flipper[:search].enable_percentage_of_time 5
 flipper[:search].disable_percentage_of_time # sets to 0
 ```
 