README.md in rspec_in_context-0.1.2 vs README.md in rspec_in_context-0.1.3

@@ -6,12 +6,10 @@
 
 This gem is here to help you write better shared_examples in Rspec.
 
 Ever been bothered by the fact that they don't really behave like methods and that you can't pass it a block ? There you go: `rspec_in_context`
 
-**NOTE**: This is an alpha version. For now context are globally scoped.
-
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -47,33 +45,37 @@
 ### Define a new in_context
 
 You can define in_context block that are reusable almost anywhere.
 They completely look like normal Rspec.
 
-##### Inside a Rspec block
+##### Inside a Rspec block (scoped)
 
 ```ruby
 # A in_context can be named with a symbol or a string
 define_context :context_name do
   it 'works' do
     expect(true).to be_truthy
   end
 end
 ```
 
-##### Outside a Rspec block
+Those in_context will be scoped to their current `describe`/`context` block.
 
-Outside of a test you have to use `RSpec.define_context`.
+##### Outside a Rspec block (globally)
 
+Outside of a test you have to use `RSpec.define_context`. Those in_context will be defined globally in your tests.
 
+
 ### Use the context
 
-Anywhere in your test description, use a `in_context` block to use a predefined in_context. **They don't need to be in the same file.** Example:
+Anywhere in your test description, use a `in_context` block to use a predefined in_context.
 
+**Important**: in_context are scoped to their current `describe`/`context` block. If you need globally defined context see `RSpec.define_context`
+
 ```ruby
 # A in_context can be named with a symbol or a string
-define_context :context_name do
+RSpec.define_context :context_name do
   it 'works' do
     expect(true).to be_truthy
   end
 end
 
@@ -84,10 +86,11 @@
 ```
 
 ### Things to know
 
 * You can chose exactly where your inside test will be used:
+
 By using `execute_tests` in your define context, the test passed when you *use* the context will be executed here
 
 ```ruby
 define_context :context_name do
   it 'works' do
@@ -107,11 +110,13 @@
     expect(pomme).to eq("abcd") # => true
   end
 end
 ```
 
-* You can add variable instantiation relative to your test where you exactly want
-It's an alias of `execute_tests` so you can't use both. But it let you describe what the block will do better.
+* You can add variable instantiation relative to your test where you exactly want:
+
+`instanciate_context` is an alias of `execute_tests` so you can't use both.
+But it let you describe what the block will do better.
 
 * You can use variable in the in_context definition
 
 ```ruby
 define_context :context_name do |name|