Readme update for clarity

README.md

@@ -1,62 +1,79 @@
 # crates.io
 
-Source code for the default registry for Cargo users. Can be found online at
-[crates.io][crates-io]
+Source code for the default [Cargo](http://doc.crates.io) registry. Viewable 
+online at [crates.io](https://crates.io).
 
-[crates-io]: https://crates.io
+This project is built on ember-cli and cargo, visit
+[iamstef.net/ember-cli](http://ember-cli.com/) or
+[doc.crates.io](http://doc.crates.io/) respectively for more information.
 
-## Development Setup
+## Working on the Frontend
 
-* `git clone` this repository
-* `npm install`
-* `npm install -g ember-cli`
-* `npm install -g bower && bower install`
-
-## Making UI tweaks or changes
+```
+git clone https://github.com/rust-lang/crates.io.git
+cd crates.io/
+npm install
+npm install -g ember-cli bower
+bower install
+```
 
-This website is built using [Ember.js](http://emberjs.com/) for the frontend,
-which enables tweaking the UI of the site without actually having the server
-running locally. To get up and running with just the UI, run:
+The website's frontend is built with [Ember.js](http://emberjs.com/). This 
+makes it possible to work on the frontend without running a local backend.
+To start the frontend run:
 
-```
+```bash
 npm run start:staging
 ```
 
-This will give you a local server to browse while using the staging backend
-(hosted on heroku at https://staging-crates-io.herokuapp.com).
+This will run a local frontend using the staging backend (hosted on Heroku at 
+[staging-crates-io.herokuapp.com](https://staging-crates-io.herokuapp.com)).
 
-If you'd like to run the server with a specific different backend, you can specify specific arguments to `npm start`. For example you can set the proxy to `https://crates.io/` to use the live instance, but do be aware that any modifications made here will be permanent! To do this, run:
+If you'd like to run the frontend with a specific backend endpoint, you can 
+specify arguments to `npm start`. For example you can set the proxy to 
+`https://crates.io/` to use the production version. 
 
-```
+**Note: it is also possible to make changes to the production data**
+
+To do this, run:
+
+```bash
 npm start -- --proxy https://crates.io
+# or
+npm run start:live
 ```
 
-The same is also available as:
+**Note**: This requires npm 2.
+
+### Running Tests
+
+Install [phantomjs](http://phantomjs.org/), typically: `npm install 
+phantomjs-prebuilt`.
+
+Then run the tests with:
 
 ```
-npm run start:live
+ember test
+ember test --server
 ```
 
-This requires NPM 2.0.
+## Working on the Backend
 
-## Working on the backend
-
-If you'd like to change the API server (the Rust backend), then the setup is a
-little more complicated.
+After cloning the repo, steps for setting up the backend API server are as 
+follows:
 
 1. Copy the `.env.sample` file to `.env` and change any applicable values as
     directed by the comments in the file. Make sure the values in your new
     `.env` are exported in the shell you use for the following commands.
 
-2. Set up the git index
+2. Set up the git index:
 
     ```
     ./script/init-local-index.sh
     ```
 
     But *do not* modify your `~/.cargo/config` yet. Do that after step 3.
 
-3. Build the server.
+3. Build the server:
 
     ```
     cargo build
@@ -65,23 +82,25 @@ little more complicated.
     On OS X 10.11, you will need to install the openssl headers first, and tell
     cargo where to find them. See https://github.com/sfackler/rust-openssl#osx.
 
-4. Run the migrations
+4. Run the migrations:
 
     ```
     ./target/debug/migrate
     ```
 
-5. Run the servers
+5. Start the backend server:
 
     ```
-    # In one window, run the api server
     ./target/debug/server
+    ```
+
+6. **Optionally** start a local frontend:
 
-    # In another window run the ember-cli server
+    ```
     npm run start:local
     ```
 
-## Running Tests
+### Running Tests
 
 1. Configure the location of the test database. Note that this should just be a
    blank database, the test harness will ensure that migrations are run.
@@ -99,30 +118,13 @@ little more complicated.
     export S3_BUCKET=alexcrichton-test
     ```
 
-3. Run the API server tests
+3. Run the backend API server tests:
 
     ```
     cargo test
     ```
 
-4. Install [phantomjs](http://phantomjs.org/)
-
-5. Run frontend tests
-
-    ```
-    ember test
-    ember test --server
-    ```
-
-## Tools
-
-For more information on using ember-cli, visit
-[http://iamstef.net/ember-cli/](http://ember-cli.com/).
-
-For more information on using cargo, visit
-[doc.crates.io](http://doc.crates.io/).
-
-## Deploying a Mirror
+## Deploying & Using a Mirror
 
 **DISCLAIMER: The process of setting up a mirror is a work-in-progress and is
 likely to change. It is not currently recommended for mission-critical
@@ -156,7 +158,7 @@ The only config variable you need to set is `GIT_REPO_URL`, which should be the
 git URL of your crates index repository; see the next section for setup
 instructions for that.
 
-### Index mirror setup
+### Index Mirror Setup
 
 You also need a mirror of the crates.io git index, and your index needs to point
 to your API server.
@@ -178,7 +180,7 @@ to your API server.
     official index. How to do this depends on how you are hosting your index,
     but could be done through `cron` or a scheduled CI job, for example.
 
-### Cargo setup
+### Local Cargo Setup
 
 **NOTE: The following configuration requires a cargo version newer than
 0.13.0-nightly (f09ef68 2016-08-02). The version of cargo that comes with rust