diff --git a/README.md b/README.md
index 598791f..747a580 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,53 @@
 # ES6 Koans
 
-You need to have `node/npm and git` installed on your computer.
+In this set of examples and tests we cover ES6 Koans concepts such as 
+ - arrow function,
+ - class
+ - iterator
+ - ...
 
+### Quick start
+**Make sure you have Node version >= 6.0 and NPM >= 3**
 
-## Clone and install repo using git
+> Clone/Download the repo then edit `*.spec.js` files inside [`/test/`](/test/)
 
+> Replace all `__` to fix failing tests
 
-Follow these few steps in order to use this repo
+```bash
+# clone our repo
+git clone https://github.com/hackages/es6.koans
 
-```
-$ git clone https://github.com/hackages/es6.koans.git
+# change directory to our repo
+cd advanced.js.koans
+
+# start the server (`npm install` will be performed for you)
+npm start
 
-$ cd es6.koans
+# start your tests in the console (`npm install` will be performed for you)
+npm test
 
-$ npm test
 ```
+go to [http://localhost:8080](http://localhost:8080) in your browser
+
+**We use Mocha in this repository**
+
+**For those using `yarn`, make sure to remove the `prestart` script before running `yarn**
 
-## You can also download the repo from [Github](https://github.com/hackages/es6.koans)
+**For those using **WallabyJS**, just run it and you'll be on your way to master JS syntax**
 
-## Recommended Tools
+### Recommended Tools
 
 1. You can use your favorite IDE but we recommend using one of those that support WallabyJS
-    1. [Atom.io ](https://atom.io/)
-    2. WebStorm
-    3. Any other IDEs
+    * [Visual Studio Code](https://code.visualstudio.com/)
+    * [Atom.io ](https://atom.io/)
+    * WebStorm
+    * Any other IDEs
 2. If you haven’t done so just install [Wallabyjs](http://wallabyjs.com)
-3. We will be using babel and Webpack
+
+## Contributing
+
+Feel free to send us PRs
+
+Happy coding!
+
+[Hackages Team](http://hackages.io)