diff --git a/README.md b/README.md
index 8d7e782..d0ee7a5 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,106 @@
 
-# release-changelog-builder
+# release-changelog-builder-action
 
-## Usage
+Builds the release notes between two tags (or refs) from pull requests merged.
+
+## Action usage
+
+Include this action in your build by defining the action in your workflow:
+
+```yml
+- name: "Build Changelog"
+  id: build_changelog
+  if: startsWith(github.ref, 'refs/tags/')
+  uses: mikepenz/release-changelog-builder-action@{latest-release}
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+This will automatically pull the tag from the current commit (the latest tag), and try to resolve the tag before this.
+
+## Action outputs
+
+The result of this action is returned via the outputs, and can be retrieved via the `changelog` value in the step afterwards. See the `test.yml` for a sample.
+
+```yml
+${{steps.build_changelog.outputs.changelog}}
+```
+
+## Configuration
+
+By default the action will look for a file called `configuration.json` within the root of the repository to load the config from. If this file does not exist, defaults are used.
+
+```
+{
+    "categories": [
+        {
+            "title": "## 🚀 Features",
+            "labels": ["feature"]
+        },
+        {
+            "title": "## 🦄 Internal Features",
+            "labels": ["internal"]
+        },
+        {
+            "title": "## 🐛 Fixes",
+            "labels": ["fix"]
+        },
+        {
+            "title": "## 🧪 Tests",
+            "labels": ["test"]
+        }
+    ],
+    "sort": "ASC",
+    "template": "${{CHANGELOG}}\n\n<details>\n<summary>Uncategorized</summary>\n\n${{UNCATEGORIZED}}\n</details>",
+    "pr_template": "- ${{TITLE}}\n   - PR: #${{NUMBER}}",
+    "empty_template": "- no changes",
+    "transformers": [
+        {
+            "pattern": "[\\-\\*] (\\[(...|TEST|CI|SKIP)\\])( )?(.+?)\n(.+?[\\-\\*] )(.+)",
+            "target": "- $4\n  - $6"
+        }
+    ]
+}
+```
+
+Any section of the configruation can be ommited, to have defaults apply
 
 
+## Advanced workflow specification
+
+For advanced usecases additional settings can be provided to the action
+
+```yml
+- name: "Complex Configuration"
+  id: build_changelog
+  if: startsWith(github.ref, 'refs/tags/')
+  uses: mikepenz/release-changelog-builder-action@{latest-release}
+  with:
+    configuration: "configuration_complex.json"
+    owner: "mikepenz"
+    repo: "release-changelog-builder-action"
+    fromTag: "0.0.2"
+    toTag: "0.0.3"
+    token: ${{ secrets.GITHUB_TOKEN }} # the token to use, for a different repository a PAT is required (Personal access token)
+```
+
+## PR Template placeholders
+
+| Variable  | Description      |
+| --------- | -------------------------- |
+| `${{NUMBER}}` | Pull request number  |
+| `${{TITLE}}`  | The title of the pull request |
+| `${{URL}}` | The URL linking to the pull request   |
+| `${{MERGED_AT}}`   | The time this PR was merged   |
+| `${{AUTHOR}}`    | The author of the pull request |
+| `${{BODY}}`    | The body / description of the pull request |
+
+## Template placeholdrs
+
+| Variable  | Description      |
+| --------- | -------------------------- |
+| `${{CHANGELOG}}` | The contents of the main changelog, matching the labels as specified in the categories configuration  |
+| `${{UNCATEGORIZED}}`  | All pull requests not matching a label |
 
 # Developed By