README.md in maroon-0.7.1 vs README.md in maroon-0.8.0

@@ -20,11 +20,11 @@
 
 See the examples for detailed information on how to use maroon.
 
 Essentially you can define a context by using
 
-Context::define :context_name do
+Context.define :context_name do
    role :role_name do
       print_self do |x| #notice no symbol
          p "#{role_name} #use role_name to refer to the role of said name
       end
    end
@@ -32,11 +32,11 @@
 
 ## Running Tests
 
 If you're using Bundler, run `bundle install` to setup your environment.
 
-Run `rake test` or just `rake` to make the tests run.
+Run `rake default` or just `rake` to make the tests run.
 
 
 ## Contributing
 
 1. Fork it
@@ -45,12 +45,32 @@
 4. Make sure you can run the default rake task with no errors _twice_
 5. Commit your changes (`git commit -am 'Add some feature'`)
 6. Push to the branch (`git push origin my-new-feature`)
 7. Create new Pull Request
 
+All changes should be done to the code in the base folder or the test folder.
+The code in the base folder is the implementation of maroon. When the default rake task is executed code will be generated
+in the 'generated' folder. The code in generated will be used when running the tests.
+If all tests pass
+1. Copy the generated files from 'generated' to 'lib'
+2. Rerun the the default rake task
+3. If all tests pass copy the generated file from 'generated' to 'lib'
+4. commit and create a pull request
 
+There's a rake task (build_lib) that will do the above if you are courageous enough to potentially loose your changes.
+
 Known bugs
-There are a few known bugs. The two major once are that #{...} syntax in strings can't beused. This is due to
-limitaion/bug in the current version of sourcify.
-If declaring several role methods for the same role sourcify might get confused and return the same sexp for
-multiple of them. The work around is to use do...end for the role ans {|| } for the role methods
+1. There are a few known bugs. The two major once are that double quotes can't be used. This is due to
+limitation/bug in the current version of sourcify.
+2. Using 'self' in a role method points to the context itself where it should be the role player
 
+
+
+Short description of the flow
+The class named Context (defined in maroon_base.rb) will read and parse the block passed to the Context.define method
+When the parsing is complete each method will be represented by an AST (using S-expressions). The transformer context
+will take over from this point. In time it runs through the definition of all roles (including there methods) and interactions.
+For each method it will use the AstRewritter context to rewrite the methods (e.g. call the correct method on the context
+object when a role method is called). The AstRewritter is build on another context namely the AbstractSyntaxTree that is used to represent
+and semantics to the abstract syntax tree (S-expressions) that represents each method.
+When all methods have been rewritten the transformer will either write the corresponding class definition to file (if so specified)
+or create a class in memory.
\ No newline at end of file