diff --git a/docs/behaviour.md b/docs/behaviour.md
new file mode 100644
index 0000000000000000000000000000000000000000..9a33b9823b8ed5f4f5084aacbcab8a0a8baadd87
--- /dev/null
+++ b/docs/behaviour.md
@@ -0,0 +1,58 @@
+# Script Behaviour
+
+This file documents the design choices as well as configuration options.
+
+## Synchronous Operation
+
+The script current processes repositories, package files, and dependencies within them all synchronously.
+- Greatly reduces chance of hitting GitHub API limits
+- Implicitly enables any feature that results in multiple commits in the same branch
+- Simplifies logging
+
+Note: Initial queries to NPM are done in parallel.
+
+## Multiple Configuration Methods
+
+The script supports multiple [configuration methods](configuration.md) concurrently, and processed in order of priority.
+This allows examples such as token configured via environment variable and labels configured via target `package.json`.
+
+## Cascading Configuration
+
+Configuration options applied per-package file override those per-repository, which override those which are global (all repositories).
+
+The following options apply per-package file:
+
+- Dependency Types
+- Ignored Dependencies
+- Labels
+- Recreate PRs
+
+The following options apply per-repository:
+
+- Token
+
+The following options apply globally:
+
+- Log Level
+
+## One PR per Major release
+
+`renovate` will create multiple branches/PRs if multiple major branch upgrades are available. For example if the current example is 1.6.0 and upgrades to 1.7.0 and 2.0.0 exist, then `renovate` will raise PRs for both the 1.x upgrade(s) and 2.x upgrade(s).
+
+- It's often the case that projects can't upgrade major dependency versions immediately.
+- It's also often the case that previous major versions continue receiving Minor or Patch updates.
+- Projects should get Minor and Patch updates for their current Major release even if a new Major release exists
+
+## Branch naming
+
+Branches are named like `renovate/webpack-1.x` instead of `renovate/webpack-1.2.0`.
+
+- Branches often receive updates (e.g. new patches) before they're merged.
+- Naming the branch like `1.x` means its name still names sense if a `1.2.1` release happens
+
+Note: Branch names are configurable using the `templates` field.
+
+## Pull Request Recreation
+
+By default, the script does not create a new PR if it finds an identical one already closed. This allows users to close unwelcome upgrade PRs and worry about them being recreated every run. Typically this is most useful for major upgrades.
+This option is configurable.
diff --git a/docs/configuration.md b/docs/configuration.md
index 39f93db17e50af0de22206b57b6baefb07f1cebf..da39b8e9e44db6d19836c662617f9a925e0c3a5c 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -87,13 +87,14 @@ Obviously, you can't set repository or package file location with this method.
## Configuration Options
-| Option | Description | Default value | File field | Environment | CLI |
+| Option | Description | Default value | File | Environment | CLI |
|---------------------|---------------------------------------------------------|-----------------------------------------------------------|---------------------------|--------------------------|---------------------------|
-| Auth Token | GitHub Personal Access Token | | `token` | `RENOVATE_TOKEN` | `--token` |
-| Repositories | List of Repositories | | `repositories` | `RENOVATE_REPOS` | Space-delimited arguments |
-| Package Files | Package file location(s) | `package.json` | `repository.packageFiles` | `RENOVATE_PACKAGE_FILES` | `--package-files` |
-| Dependency Types | Sections of package.json to renovate | `dependencies`, `devDependencies`, `optionalDependencies` | `depTypes` | `RENOVATE_DEP_TYPES` | `--dep-types` |
-| Ignore Dependencies | Dependencies to be ignored | | `ignoreDeps` | `RENOVATE_IGNORE_DEPS` | `--ignore-deps` |
-| Labels | Labels to add to Pull Requests | | `labels` | `RENOVATE_LABELS` | `--labels` |
-| Recreate PRs | Create New PRs even if same ones were previously closed | `false` | `recreatePrs` | `RENOVATE_RECREATE_PRS` | `--recreate-prs` |
-| Log Level | Log Level | `info` | `logLevel` | `LOG_LEVEL` | `--log-level` |
+| Auth Token | GitHub Personal Access Token | | `token` | `RENOVATE_TOKEN` | `--token` |
+| Repositories | List of Repositories | | `repositories` | `RENOVATE_REPOS` | Space-delimited arguments |
+| Package Files | Package file location(s) | `package.json` | `repository.packageFiles` | `RENOVATE_PACKAGE_FILES` | `--package-files` |
+| Dependency Types | Sections of package.json to renovate | `dependencies`, `devDependencies`, `optionalDependencies` | `depTypes` | `RENOVATE_DEP_TYPES` | `--dep-types` |
+| Ignore Dependencies | Dependencies to be ignored | | `ignoreDeps` | `RENOVATE_IGNORE_DEPS` | `--ignore-deps` |
+| Labels | Labels to add to Pull Requests | | `labels` | `RENOVATE_LABELS` | `--labels` |
+| Recreate PRs | Create New PRs even if same ones were previously closed | `false` | `recreatePrs` | `RENOVATE_RECREATE_PRS` | `--recreate-prs` |
+| Log Level | Log Level | `info` | `logLevel` | `LOG_LEVEL` | `--log-level` |
+| Templates | String templates for commit, branch and PR | Multiple | `templates` | | |
diff --git a/docs/deployment.md b/docs/deployment.md
new file mode 100644
index 0000000000000000000000000000000000000000..ce59ee029c76692ae99917415469d6fbdfd24c21
--- /dev/null
+++ b/docs/deployment.md
@@ -0,0 +1,61 @@
+# Deployment
+
+Before deploying the script for scheduled runs, it's recommend you test your settings locally first.
+
+## Server cron
+
+Adding `renovate` as a `cron` job is the simplest way to deploy.
+
+### Installation
+
+Install using `npm install -g`.
+
+### Configuration
+
+At a minimum, you will need to configure the token and repository list.
+Simplest would be to specify both via CLI.
+Alternatively, configure the token via Environment Variable if you don't want it to show in any cron logs.
+
+Running daily should suit most people. At most, hourly.
+
+## Heroku
+
+Heroku free dynos provide a good way to host this for free. Set it up with the following commands:
+
+### Installation
+
+The best way to deploy to Heroku is via git and Heroku CLI.
+
+```
+$ git clone https://github.com/singapore/renovate
+$ cd renovate
+$ heroku create [app name]
+$ git push heroku master
+$ heroku ps:scale web=0
+```
+
+### Configuration
+
+You now need to set the token.
+
+```
+$ heroku config:set RENOVATE_TOKEN=[YourGitHubToken]
+```
+
+You should also set any other [Configuration Options](configuration.md) you need.
+
+The app should now be ready for testing.
+
+```
+$ heroku run node renovate [your/repo]
+```
+
+Once you've verified the script ran successfully, it's time to set it up for automatic scheduling.
+```
+$ heroku addons:create scheduler:standard
+$ heroku addons:open scheduler
+```
+
+At this point you should have the Heroku Scheduler Dashboard open. Click "Add new job" and enter the same command as you ran previously (e.g. `node renovate [your/repo]`). Adjust the frequency to hourly if you prefer, then click Save.
+
+You can run `heroku logs` to check execution logs. Consider adjusting the scripts log level if you have problems (info -> verbose -> debug -> silly).
diff --git a/readme.md b/readme.md
index eed560f434be1342863cdcadda4ff4f26f8cca94..3aae4c518f425fa6c9afa0a5b9ec18be6ef1606c 100644
--- a/readme.md
+++ b/readme.md
@@ -50,3 +50,11 @@ $ renovate --help
$ renovate --token abc123 -l verbose singapore/lint-condo
$ renovate --token abc123 singapore/lint-condo singapore/package-test
```
+
+## Deployment
+
+See [deployment docs](docs/deploment.md) for details.
+
+## Behaviour
+
+See [behaviour docs](docs/behaviour.md) for details.