README.md

@@ -5,23 +5,24 @@
 This README outlines the details of collaborating on this Ember application.
 A short introduction of this app could easily go here.
 
-## Prerequisites
+## Development
+
+### Prerequisites
 
 You will need the following things properly installed on your computer.
 
 * [Git](https://git-scm.com/)
 * [Node.js](https://nodejs.org/) (with npm)
 * [Ember CLI](https://ember-cli.com/)
-* [Google Chrome](https://google.com/chrome/)
+* [Google Chrome](https://google.com/chrome/) (only for running tests)
 
-## Installation
+### Installation
 
 * `git clone git@github.com:67P/kredits-web.git` this repository
 * `cd kredits-web`
 * `npm install`
 
-## Running / Development
-
+### Building/running for development
 
 * `ember serve` - by default kredits-web connects to the Ethreum Kovan network
 * Visit your app at [http://localhost:4200](http://localhost:4200).
@@ -29,11 +30,11 @@ You will need the following things properly installed on your computer.
 
 See [working with locally deployed contracts](https://github.com/67P/kredits-web#working-with-locally-deployed-contracts) for details on how to develop with locally deployed contracts.
 
-### Code Generators
+### Code generators
 
 Make use of the many generators for code, try `ember help generate` for more details
 
-### Running Tests
+### Running tests
 
 * `ember test`
 * `ember test --server`
@@ -55,17 +56,15 @@ _(You need collaborator permissions on the 5apps Deploy project.)_
 
 `npm run deploy`
 
-## Working with locally deployed contracts
+### Working with locally deployed contracts
 
 The smart contracts and their JavaScript wrapper library are developed in the
 [kredits-contracts](https://github.com/67P/kredits-contracts) repo/package.
 
-You can run `kredits-web` on your machine, against a local, simulated Ethereum
-network, provided e.g. by [ganache](http://truffleframework.com/ganache/).
-
-[kredits-contracts](https://github.com/67P/kredits-contracts) holds all the tools
-to start and set up such a simulated network, as well as to deploy smart
-contracts to it.
+You can run `kredits-web` on your machine, against a local, simulated
+blockchain. [kredits-contracts](https://github.com/67P/kredits-contracts)
+contains all the tools to start and set up such a simulated network, as well as
+to deploy the Kredits smart contracts to it.
 
 These are the basic steps to get up and running:
 
@@ -78,31 +77,33 @@ Run a local IPFS deamon.
 
 #### 2. kredits-contracts
 
-Get your local Ethereum development node running. (See [kredits-contracts README](https://github.com/67P/kredits-contracts)
-for details.
+Run a local devchain with test data. (See [kredits-contracts
+README](https://github.com/67P/kredits-contracts) for details.
 
   * Clone [kredits-contracts](https://github.com/67P/kredits-contracts)
   * `npm install`
   * `npm run devchain` - runs a local development chain
-  * `npm run bootstrap` - bootstrap runs deploys all the contracts
-  * `npm link` - make the `kredits-contracts` module linkable as `kredits-contracts` on your machine (currently broken :( )
+  * `npm run bootstrap` - deploys all contracts and seeds test data
+  * `npm link` - makes the `kredits-contracts` module linkable as `kredits-contracts` on your machine
 
 #### 3. kredits-web
 
-With IPFS and Ethereum/ganache running, you can now start this Ember app.
+With IPFS and the local devchain running, you can now link the contracts and
+start the Ember app:
 
-  * `npm link kredits-contracts` - link the local `kredits-contracts` package
-  * `npm run start:local` - WEB3_PROVIDER_URL=http://localhost:8545 must be set for local settings
+  * `npm link kredits-contracts` - links the local `kredits-contracts` package (has to be done again after every `npm install`)
+  * `npm run start:local` - runs the Ember app with WEB3_PROVIDER_URL=http://localhost:8545 set
 
 #### 4. Metamask network
 
-Switch the network in Metamask to "Custom RPC" with the RPC URL `http://localhost:8545`.
+If you want to interact with the local contracts via a Web3 wallet, switch the
+network to a "Custom RPC" one, with the RPC URL `http://localhost:8545`.
 
 #### IPFS
 
-Install IPFS with your favorite package manager and run
+If you haven't configured your IPFS node for CORS yet, you can do so by running
+the following commands:
 
-    ipfs init (on initial installation)
     ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["localhost:4200"]'
     ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "GET", "POST"]'
     ipfs config --json API.HTTPHeaders.Access-Control-Allow-Credentials '["true"]'