diff --git a/README.md b/README.md
index dc29d8fb1..28dc6e38f 100644
--- a/README.md
+++ b/README.md
@@ -9,10 +9,20 @@ Get and update notification status.
 
 ## Setting Up
 
+### AWS credentials
+
+To run the API you will need appropriate AWS credentials. You should receive these from whoever administrates your AWS account. Make sure you've got both an access key id and a secret access key.
+
+Your aws credentials should be stored in a folder located at `~/.aws`. Follow [Amazon's instructions](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) for storing them correctly.
+
+### Virtualenv
+
 ```
 mkvirtualenv -p /usr/local/bin/python3 notifications-api
 ```
 
+### `environment.sh`
+
 Creating the environment.sh file. Replace [unique-to-environment] with your something unique to the environment. Your AWS credentials should be set up for notify-tools (the development/CI AWS account).
 
 Create a local environment.sh file containing the following:
@@ -20,30 +30,30 @@ Create a local environment.sh file containing the following:
 ```
 echo "
 export SQLALCHEMY_DATABASE_URI='postgresql://localhost/notification_api'
-export SECRET_KEY='secret-key'
-export DANGEROUS_SALT='dangerous-salt'
-export NOTIFY_ENVIRONMENT="development"
-export ADMIN_CLIENT_SECRET='notify-secret-key'
+export SECRET_KEY='dev-notify-secret-key'
+export DANGEROUS_SALT='dev-notify-salt'
+export NOTIFY_ENVIRONMENT='development'
+export ADMIN_CLIENT_SECRET='dev-notify-secret-key'
 export ADMIN_BASE_URL='http://localhost:6012'
 export FROM_NUMBER='development'
-export MMG_URL="https://api.mmg.co.uk/json/api.php"
+export MMG_URL='https://api.mmg.co.uk/json/api.php'
 export MMG_API_KEY='MMG_API_KEY'
-export LOADTESTING_API_KEY="FIRETEXT_SIMULATION_KEY"
-export FIRETEXT_API_KEY="FIRETEXT_ACTUAL_KEY"
-export STATSD_PREFIX="FAKE_PREFIX"
-export NOTIFICATION_QUEUE_PREFIX="PREFIX-TO-IDENTIFY-SQS-QUEUE"
+export LOADTESTING_API_KEY='FIRETEXT_SIMULATION_KEY'
+export FIRETEXT_API_KEY='FIRETEXT_ACTUAL_KEY'
+export STATSD_PREFIX='YOU_OWN_PREFIX'
+export NOTIFICATION_QUEUE_PREFIX='YOUR_OWN_PREFIX'
 "> environment.sh
 ```
 
-NOTE: The SECRET_KEY and DANGEROUS_SALT should match those in the [notifications-admin](https://github.com/alphagov/notifications-admin) app.
+NOTES:
 
-NOTE:  Also note the  unique prefix for the queue names. This prevents clashing with others queues in shared amazon environment and using a prefix enables filtering by queue name in the SQS interface.
+ * Replace the placeholder key and prefix values as appropriate
+ * The SECRET_KEY and DANGEROUS_SALT should match those in the [notifications-admin](https://github.com/alphagov/notifications-admin) app.
+ * The  unique prefix for the queue names prevents clashing with others' queues in shared amazon environment and enables filtering by queue name in the SQS interface.
 
-Install Postgresql
+### Postgres
 
-```shell
-    brew install postgres
-```
+Install [Postgres.app](http://postgresapp.com/). You will need admin on your machine to do this.
 
 ##  To run the application
 
@@ -75,7 +85,7 @@ make test
 ```
 
 That will run pep8 for code analysis and our unit test suite. If you wish to run our functional tests, instructions can be found in the
-[notifications-functional-test](https://github.com/alphagov/notifications-functional-test) repository.
+[notifications-functional-tests](https://github.com/alphagov/notifications-functional-tests) repository.
 
 
 
diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh
index 5c924e59b..15c1d8ef0 100755
--- a/scripts/bootstrap.sh
+++ b/scripts/bootstrap.sh
@@ -25,6 +25,8 @@ if [ ! $VIRTUAL_ENV ]; then
   . ./venv/bin/activate
 fi
 
+# we need the version file to exist otherwise the app will blow up
+make generate-version-file
 
 # Install Python development dependencies
 pip3 install -r requirements_for_test.txt