diff --git a/README.mdown b/README.mdown
index 2b745ff..9088f65 100644
--- a/README.mdown
+++ b/README.mdown
@@ -1,9 +1,58 @@
+# Kredits
 
+This repository contains all the contracts for Kredits as a [truffle framework](http://truffleframework.com/) project.
 
 ## Development
 
-For local development it is recommended to use [ganache-cli](https://github.com/trufflesuite/ganache-cli) to run a local development chain.
+For local development it is recommended to use [ganache-cli](https://github.com/trufflesuite/ganache-cli) (or the [ganache GUI](http://truffleframework.com/ganache/) to run a local development chain.  
+Using the ganache simulator no full Ethereum node is required.
 
-We default to port 7545 for development to not get in conflict with the default Ethereum RPC port. 
+We default to the port 7545 for development to not get in conflict with the default Ethereum RPC port. Have a look at `ganache-cli` for more configuration options.
+
+Run your ganache simulator before using Kredits locally:
+
+    $ ganache-cli -p 7545
+
+### Truffle console
+
+Truffle comes with a simple REPL to interact with the Smart Contracts. Have a look at the [documentation here](http://truffleframework.com/docs/getting_started/console)
+
+NOTE: There are promisses, have a look at the examples: 
+
+``javascript
+Token.deployed().then(function(token) { 
+  token.totalSupply.call().then(function(value) {
+    console.log(value.toString());
+  })
+});
+```
+
+Also please be aware of the differences between web3.js 0.2x.x and [1.x.x](https://web3js.readthedocs.io/en/1.0/) - [web3 repo](https://github.com/ethereum/web3.js/)
+
+
+## Contract Deployment
+
+Truffle uses migration scripts to deploy contract to various networks. Have a look at the `migrations` folder for those.  
+The Ethereum nodes for the different networks need to be configured in `truffle.js`.
+
+Run the truffle migration scripts: 
+
+    $ truffle deploy 
+    $ truffle deploy --network=<network config from truffle.js>
+
+Truffle keeps track of already executed migration scripts. To reset the migration use the `--reset` option
+
+    $ truffle migrate --reset
+
+Migration scripts can also be run from within `truffle console` or `truffle develop` 
+
+
+## Upgradeable contracts
+
+Some of the contracts use upgradability ideas from [zeppelinos](https://github.com/zeppelinos/labs) (see `contracts/upgradable`).
+
+The basic idea is to have a Registry contract that knows about the current implementations and a Proxy contract that uses `delegatecall` to call the current implementation.  
+That means the Proxy contract holds the storage and the address of that one does not change but the actuall implemenation is managed through the Registry. 
+
+To deploy a new version a new contract is deployed then the version is registered (`addVersion()`) in the Registry and on the Proxy contract is "upgraded" (`upgradeTo()`) to the new version. 
 
-  $ ganache-cli -p 7545