update readme with feedback from #378

1 files changed, 25 insertions, 18 deletions

diff --git a/README.md b/README.md
index cad8e513..8d1f1b8a 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,30 @@
 Pixelated User Agent
 ====================
+
 [![Build Status](https://snap-ci.com/pixelated-project/pixelated-user-agent/branch/master/build_image)](https://snap-ci.com/pixelated-project/pixelated-user-agent/branch/master) [
 ![Coverage Status](https://coveralls.io/repos/pixelated-project/pixelated-user-agent/badge.svg?branch=master)](https://coveralls.io/r/pixelated-project/pixelated-user-agent?branch=master)
 
-The Pixelated User Agent is the mail client of the Pixelated ecosystem, it is composed of two parts, a web interface written in javascript and an API written in python that glues that interface with the Pixelated or LEAP Provider.
+The Pixelated User Agent is the mail client of the Pixelated ecosystem. It is composed of two parts, a web interface written in JavaScript ([FlightJS](https://flightjs.github.io/)) and a Python API that interacts with a LEAP Provider, the e-mail platform that Pixelated is built on.
 
 **Pixelated is still in early development state!**
 
 ![High level architecture User Agent](https://pixelated-project.org/assets/images/pixelated-user-agent.png)
 
-## Getting started
 
-### Registering with a provider
 
+## Getting started
+
+### Registering with a LEAP provider
+  * 
   * You can create a developer account at our [Dev Provider](https://dev.pixelated-project.org/).
-  * There are some other LEAP providers on the [Bitmask page](https://bitmask.net), but they don't support email currently.
-  * If you want to run your own provider, see [pixelated-platform](https://github.com/pixelated-project/pixelated-platform).
+  * If you want to run your own LEAP provider, see [pixelated-platform](https://github.com/pixelated-project/pixelated-platform).
 
 ### Requirements
-  * vagrant
-  * virtualbox
+
+  * [virtualbox](https://www.virtualbox.org/wiki/Downloads) - Virtualbox is a virtual machine provider platform. It will be used by Vagrant to create a virtual machine ready to run the Pixelated User Agent.
+  * [vagrant](https://www.vagrantup.com/downloads.html) - Vagrant is a tool that automates the setup of a virtual machine with the development environment in your computer. Inside the virtual machine's filesystem, this repository will be automatically mounted in the `/vagrant` folder.
+
+### Instructions
 
 Clone the repository:
 
@@ -28,25 +33,27 @@ Clone the repository:
 
 From the project root folder, set up the vagrant machine:
 
-    vagrant up source
+    vagrant up
 
-You can log into the machine and view project root folder with:
+After this is done, you can log into the machine and view project root folder with:
 
     vagrant ssh
-    
- Then you need to run the setup:
+    cd /vagrant
+
+Then run the setup:
  
-    cd service
+    cd /vagrant/service
     ./go setup
-    
-From here on you can run the tests for the UI by going to the **web-ui** folder or for the API by going to the **service** folder:
+ 
+From here on you can run the tests for the UI by going to the **web-ui** folder or for the REST API by going to the **service** folder:
 
     cd /vagrant/web-ui
     ./go test
-    
+
     cd /vagrant/service
     ./go test
-Running the user agent:
+    
+To run the user agent:
 
 ```
 $ pixelated-user-agent --host 0.0.0.0 -lc /vagrant/service/pixelated/certificates/dev.pixelated-project.org.ca.crt
@@ -59,11 +66,11 @@ username
 *******************
 ```
 
-As soon as the agent starts you will be asked for username, password and the [provider you registered with](https://github.com/pixelated-project/pixelated-user-agent/blob/master/README.md#registering-with-a-provider). 
+As soon as the user agent starts you will be asked for username, password and the [provider you registered with](https://github.com/pixelated-project/pixelated-user-agent/blob/master/README.md#registering-with-a-provider). 
 
 Now you can see it running on [http://localhost:3333](http://localhost:3333)
 
-##Debian package
+## Debian package
 
 For people that just want to try the user agent, we have debian packages available in our [repository](http://packages.pixelated-project.org/debian/). To use it you have to add it to your sources list: