diff --git a/plugins/git-hubflow/README.md b/plugins/git-hubflow/README.md
new file mode 100644
index 000000000..dada60d78
--- /dev/null
+++ b/plugins/git-hubflow/README.md
@@ -0,0 +1,24 @@
+# git-hubflow plugin
+
+This plugin adds completion for [HubFlow](https://datasift.github.io/gitflow/) (GitFlow for GitHub), as well as some
+aliases for common commands. HubFlow is a git extension to make it easy to use GitFlow with GitHub. Based on the
+original gitflow extension for git.
+
+The hubflow tool has to be [installed](https://github.com/datasift/gitflow#installation) separately.
+
+To use it, add `git-hubflow` to the plugins array in your zshrc file:
+
+```zsh
+plugins=(... git-hubflow)
+```
+
+## Aliases
+
+| Alias | Command          | Description                                                      |
+|-------|------------------|------------------------------------------------------------------|
+| ghf   | `git hf`         | Print command overview                                           |
+| ghff  | `git hf feature` | Manage your feature branches                                     |
+| ghfr  | `git hf release` | Manage your release branches                                     |
+| ghfh  | `git hf hotfix`  | Manage your hotfix branches                                      |
+| ghfs  | `git hf support` | Manage your support branches                                     |
+| ghfu  | `git hf update`  | Pull upstream changes down into your master and develop branches |
diff --git a/plugins/git-hubflow/git-hubflow.plugin.zsh b/plugins/git-hubflow/git-hubflow.plugin.zsh
index 8d968229f..05479f7e6 100644
--- a/plugins/git-hubflow/git-hubflow.plugin.zsh
+++ b/plugins/git-hubflow/git-hubflow.plugin.zsh
@@ -1,25 +1,3 @@
-#!zsh
-#
-# Installation
-# ------------
-#
-# To achieve git-hubflow completion nirvana:
-#
-#  0. Update your zsh's git-completion module to the newest version.
-#     From here: https://github.com/zsh-users/zsh/blob/master/Completion/Unix/Command/_git
-#
-#  1. Install this file. Either:
-#
-#     a. Place it in your .zshrc:
-#
-#     b. Or, copy it somewhere (e.g. ~/.git-hubflow-completion.zsh) and put the following line in
-#        your .zshrc:
-#
-#            source ~/.git-hubflow-completion.zsh
-#
-#     c. Or, use this file as an oh-my-zsh plugin.
-#
-
 alias ghf='git hf'
 alias ghff='git hf feature'
 alias ghfr='git hf release'