Harmonisation toolbox readme template

Work in progress befitting certs status

README.md

@@ -14,13 +14,61 @@ This source code is for the ODI's Open Data Certificates app at [certificates.th
 
 This code is open source under the MIT license. See [LICENSE.md](LICENSE.md) file for full details.
 
+## Summary of features
+
+This is a rails app
+{software - high level description, FAO contributors}
+LINK_TO roadmap
+
 ## Development
 
-The simplest way to get a certificates app up and running is under Docker.
+### Requirements
+ruby version 2.1.8
 
-### With Docker
+### Environment variables
 
-#### OSX 
+Some extra environment variables are required for the certificates site; these can be set in a .env file in the root of the project. The docker setup will create this file if it doesn't already exist.
+
+#### Required
+
+```
+# A hostname to create links in emails
+CERTIFICATE_HOSTNAME="localhost:3000"
+
+# Redis server URL
+ODC_REDIS_SERVER_URL="redis://redis:6379"
+```
+
+#### Optional
+
+The following extra are needed in production or for optional features:
+
+```
+# Rackspace credentials for saving certificate dumps
+RACKSPACE_USERNAME
+RACKSPACE_API_KEY
+RACKSPACE_CERTIFICATE_DUMP_CONTAINER
+
+# Juvia details to allow commenting
+JUVIA_BASE_URL
+CERTIFICATE_JUVIA_SITE_KEY
+
+# Sending error reports to airbrake
+AIRBRAKE_CERTIFICATE_KEY
+
+# Enable footnotes for debugging info
+ENABLE_FOOTNOTES=true
+```
+
+### Specific Development Notes
+
+### Development: Running the full application locally
+
+#### With Docker
+
+The simplest way to get a certificates app up and running is under Docker.
+
+##### OSX 
 
 1. Install [Docker Toolbox](https://www.docker.com/products/docker-toolbox)
   * Set up a Docker host with `docker-machine start default` or run the Kitematic GUI.
@@ -32,7 +80,7 @@ The simplest way to get a certificates app up and running is under Docker.
 4. Everything should be set up and be open in your browser.
 5. Run `docker-compose run web bin/setup`
 
-#### Linux
+##### Linux
 
 1. Install [docker-engine](https://docs.docker.com/engine/), [docker-compose](https://docs.docker.com/compose/overview/), and then [docker-machine](https://docs.docker.com/machine/overview/)
 2. Set up a Docker host with `docker-machine create -d virtualbox default`
@@ -43,33 +91,32 @@ The simplest way to get a certificates app up and running is under Docker.
   * Then point your browser to the address:port for the `opendatacertificate_web_1` container (likely `0.0.0.0:3000`)
 6. Run `docker-compose run web bin/setup`
 
-### Without Docker
+##### Without Docker
 
 1. Install Ruby 2.1.8, and bundler.
 2. Install and run Redis and MySQL servers.
-3. Run `bin/setup`
-4. Run `bundle exec rails s`
+3. Run `bin/setup` (generates `.env` file)
+4. edit the default config/database.yml #TODO with what?
+5. Run `bundle exec rails s`
 
 If you're not using docker, ignore the `docker-compose run web` prefix on the commands below.
 
-### Default Admin User
-
-Both of the above methods should set up your local app with a default admin user:
+###### Known issues
 
-* Username: `test@example.com`
-* Password: `testtest`
+eventmachine
+rubyracer
 
-## Testing
+#### Application Configuration
 
-To run tests:
+##### Default Admin User
 
-    docker-compose run web bundle exec rake test
+Both of the above methods should set up your local app with a default admin user:
 
-You can also run tests continuously whenever a file is changed:
+* Username: `test@example.com`
+* Password: `testtest`
 
-    docker-compose run web bundle exec guard
 
-## Internationalisation
+##### Internationalisation
 
 By default, only the UK survey is built in development, as building more can take a while.    
 
@@ -87,46 +134,23 @@ To build *all* the other surveys (remember, this can take a while):
 
 For information on how to translate and localise surveys, see below.
 
-## API
-
-Certificates can be created and updated using a JSON API. See the [API documentation](doc/api.md) for details.
+#### Testing
 
-## Environment variables
-
-Some extra environment variables are required for the certificates site; these can be set in a .env file in the root of the project. The docker setup will create this file if it doesn't already exist.
-
-### Required
-
-```
-# A hostname to create links in emails
-CERTIFICATE_HOSTNAME="localhost:3000"
-
-# Redis server URL
-ODC_REDIS_SERVER_URL="redis://redis:6379"
-```
+To run tests:
 
-### Optional
+    docker-compose run web bundle exec rake test
 
-The following extra are needed in production or for optional features:
+You can also run tests continuously whenever a file is changed:
 
-```
-# Rackspace credentials for saving certificate dumps
-RACKSPACE_USERNAME
-RACKSPACE_API_KEY
-RACKSPACE_CERTIFICATE_DUMP_CONTAINER
+    docker-compose run web bundle exec guard
 
-# Juvia details to allow commenting
-JUVIA_BASE_URL
-CERTIFICATE_JUVIA_SITE_KEY
+### API
 
-# Sending error reports to airbrake
-AIRBRAKE_CERTIFICATE_KEY
+Certificates can be created and updated using a JSON API. See the [API documentation](doc/api.md) for details.
 
-# Enable footnotes for debugging info
-ENABLE_FOOTNOTES=true
-```
+### Application Functionality
 
-## Admin functions
+#### Admin functions
 
 To mark a user as being an admin use the rails console to set the `admin` field to true. The easiest way to find the ID is to look on the URL of their account page.
 
@@ -136,7 +160,7 @@ Admins are able to block a dataset from displaying on the public /datasets page
 
 Removed datasets are listed at `/datasets/admin` (only accessible by admin users).
 
-## Autocompletion
+#### Autocompletion
 
 The survey attempts to fetch answers from the documentation URL and fill them into the questionnaire. These answers are marked as autocompleted.
 
@@ -154,7 +178,7 @@ Some examples of URLS that can be autocompleted:
 - http://data.ordnancesurvey.co.uk/datasets/boundary-line
 - http://smtm.labs.theodi.org/download/
 
-## Additional documentation
+### Additional documentation
 
 [App approach document](https://docs.google.com/a/whiteoctober.co.uk/document/d/1Ot91x1enq9TW7YKpePytE-wA0r8l9dmNQLVi16ph-zg/edit#)