diff --git a/README.md b/README.md
index ccca5acd5..d9eeb46de 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
-
+
[Website](https://www.accent.reviews) • [GraphiQL](https://www.accent.reviews/documentation)
@@ -28,68 +28,72 @@ The Accent API provides a powerful abstraction around the process of translating
## Requirements
-- Erlang OTP 20.1
-- Elixir 1.6.2
-- PostgreSQL >= 9.4
-- Node.js >= 8.5.0
-- libyaml
+- `erlang ~> 20.1`
+- `elixir ~> 1.6.0`
+- `postgres >= 9.4`
+- `node.js >= 8.5.0`
+- `libyaml >= 0.1.7`
## Executing mix commands
-The app is modeled with the _Twelve-Factor_ architecture, all configurations are stored in the environment.
+The app is modeled with the [_Twelve-Factor App_](https://12factor.net/) architecture, all configurations are stored in the environment.
-When executing mix command, you should always make sure that the required system `ENV` are present. You can `source`, use [nv](https://github.com/jcouture/nv) or a custom l33t bash script.
+When executing `mix` commands, you should always make sure that the required environment variables are present. You can `source`, use [nv](https://github.com/jcouture/nv) or a custom l33t bash script.
Every following steps assume you have this kind of system.
-But Accent can be run with default env var if you have a PostgreSQL user named postgres listening on port 5432 on localhost.
+
+But Accent can be run with default environment variables if you have a PostgreSQL user named `postgres` listening on port `5432` on `localhost`.
### Example
With `nv` you inject the environment keys in the context with:
-```shell
-> nv .env mix
-
+```
+$ nv .env mix
```
## Quickstart
- 1. If you don’t already have it, install `nodejs` with `brew install nodejs`
- 1. If you don’t already have it, install `elixir` with `brew install elixir`
- 2. If you don’t already have it, install `libyaml` with `brew install libyaml`
- 2. If you don’t already have it, install `PostgreSQL` with `brew install postgres` or the [macOS app](https://postgresapp.com/)
- 3. Install dependencies with `mix deps.get` and `npm --prefix webapp install`.
- 4. Create and migrate your database with `mix ecto.setup`
- 5. Start Phoenix endpoint with `mix phx.server`
- 5. Start Ember server with `npm --prefix webapp run start`
- 6. That’s it.
+1. If you don’t already have it, install `nodejs` with `brew install nodejs`
+1. If you don’t already have it, install `elixir` with `brew install elixir`
+2. If you don’t already have it, install `libyaml` with `brew install libyaml`
+2. If you don’t already have it, install `postgres` with `brew install postgres` or the [macOS app](https://postgresapp.com/)
+3. Install dependencies with `mix deps.get` and `npm --prefix webapp install`.
+4. Create and migrate your database with `mix ecto.setup`
+5. Start Phoenix endpoint with `mix phx.server`
+5. Start Ember server with `npm --prefix webapp run start`
+6. That’s it!
## Environment variables
-This app provides default value for every env var. This means that with the right PostgreSQL setup, you can just run `mix phx.server`.
+Accent provides a default value for every required environment variable. This means that with the right PostgreSQL setup, you can just run `mix phx.server`.
-- `DATABASE_URL=postgres://localhost/accent_development`: A valid database url. Like the one used by Heroku.
-- `PORT=4000`: A PORT to run your app.
-- `WEBAPP_PORT=4200`: A PORT to run your webapp. (only used in dev)
-- `API_HOST=http://localhost:4000`: The host of the API.
-- `API_WS_HOST=ws://localhost:4000`: The websocket host of the API.
-- `MIX_ENV=dev` : Environment to run mix {dev, prod, test}
-- `WEBAPP_EMAIL_HOST=localhost:8001`: Web client’s hostname. Used in the sent emails to link to the right URL. There is no default value, please provide a value if you want to send emails.
-- `MAILER_FROM=anEmail@gmail.com`: Email address used in the sent email. There is no default value, please provide a value if you want to send emails.
+| Variable | Default | Description |
+|---------------------|-------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `MIX_ENV` | `dev` | The application environment (`dev`, `prod`, or `test`) |
+| `DATABASE_URL` | `postgres://localhost/accent_development` | A valid database URL |
+| `PORT` | `4000` | A PORT to run the API on |
+| `WEBAPP_PORT` | `4200` | A PORT to run the Webapp on (only used in `dev` environment) |
+| `API_HOST` | `http://localhost:4000` | The API host |
+| `API_WS_HOST` | `ws://localhost:4000` | The API Websocket host |
+| `WEBAPP_EMAIL_HOST` | _none_ | The Web client’s hostname. Used in the sent emails to link to the right URL. There is no default value, please provide a value if you want to send emails. |
+| `MAILER_FROM` | _none_ | The email address used to send emails. There is no default value, please provide a value if you want to send emails. |
### Production setup
-- `SENTRY_DSN`
-- `WEBAPP_SENTRY_DSN`
-- `GOOGLE_API_CLIENT_ID`: When deploying in a production env, the Google login is the only way to authenticate user. In dev, a fake login provider is used so you don’t have to setup a Google app.
+| Variable | Default | Description |
+|------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `SENTRY_DSN` | _none_ | The *secret* Sentry DSN used to collect API runtime errors |
+| `WEBAPP_SENTRY_DSN` | _none_ | The *public* Sentry DSN used to collect Webapp runtime errors |
+| `GOOGLE_API_CLIENT_ID` | _none_ | When deploying in a `prod` environment, the Google login is the only way to authenticate user. In `dev` environment, a fake login provider is used so you don’t have to setup a Google app. |
## Tests
### API
-This app provides default value for every env var required in test. This means that with the right PostgreSQL setup, you can just run `mix test`.
+Accent provides a default value for every required environment variable. This means that with the right PostgreSQL setup (and a few setup commands), you can just run `mix test`.
-```shell
+```
$ npm --prefix webapp run build
$ mix run ./priv/repo/seeds.exs
$ mix test
@@ -97,11 +101,11 @@ $ mix test
## Deploy on Heroku
-To successfully deploy the application on Heroku, you must use these buildpacks:
+To successfully deploy Accent on Heroku, you must use these buildpacks:
_The first buildpack is to use the Aptfile to install libyaml._
-```shell
+```
$ heroku buildpacks:add --index 1 https://github.com/heroku/heroku-buildpack-apt#usr-local-paths
$ heroku buildpacks:add --index 2 https://github.com/HashNuke/heroku-buildpack-elixir
$ heroku buildpacks:add --index 3 https://github.com/gjaldon/heroku-buildpack-phoenix-static
@@ -111,12 +115,12 @@ $ heroku buildpacks:add --index 3 https://github.com/gjaldon/heroku-buildpack-ph
Before opening a pull request, please open an issue first.
-Once you've made your additions and the test suite passes, go ahead and open a PR!
+Once you’ve made your additions and the test suite passes, go ahead and open a PR!
Don’t forget to run the `./priv/scripts/ci-check.sh` script to make sure that the CI build will pass :)
## About Mirego
-[Mirego](https://www.mirego.com) is a team of passionate people who believe that work is a place where you can innovate and have fun. We're a team of [talented people](https://life.mirego.com) who imagine and build beautiful Web and mobile applications. We come together to share ideas and [change the world](http://www.mirego.org).
+[Mirego](https://www.mirego.com) is a team of passionate people who believe that work is a place where you can innovate and have fun. We’re a team of [talented people](https://life.mirego.com) who imagine and build beautiful Web and mobile applications. We come together to share ideas and [change the world](http://www.mirego.org).
We also [love open-source software](https://open.mirego.com) and we try to give back to the community as much as we can.