9 files changed, 100 insertions, 50 deletions
diff --git a/plugins/aws/README.md b/plugins/aws/README.md
new file mode 100644
index 000000000..8a45199b8
--- /dev/null
+++ b/plugins/aws/README.md
@@ -0,0 +1,20 @@
+# aws
+
+This plugin provides completion support for [awscli](https://docs.aws.amazon.com/cli/latest/reference/index.html)
+and a few utilities to manage AWS profiles: a function to change profiles with autocompletion support
+and a function to get the current AWS profile. The current AWS profile is also displayed in `RPROMPT`.
+
+To use it, add `aws` to the plugins array in your zshrc file.
+
+```zsh
+plugins=(... aws)
+```
+
+## Plugin commands
+
+* `asp <profile>`: Sets `AWS_PROFILE` and `AWS_DEFAULT_PROFILE` (legacy) to `<profile>`.
+It also adds it to your RPROMPT.
+
+* `agp`: Gets the current value of `AWS_PROFILE`.
+
+* `aws_profiles`: Lists the available profiles in the file referenced in `AWS_CONFIG_FILE` (default: ~/.aws/config). Used to provide completion for the `asp` function.
diff --git a/plugins/git-flow-avh/README.md b/plugins/git-flow-avh/README.md
new file mode 100644
index 000000000..0768d93ea
--- /dev/null
+++ b/plugins/git-flow-avh/README.md
@@ -0,0 +1,19 @@
+# git-flow (AVH Edition) plugin
+
+This plugin adds completion for the [git-flow (AVH Edition)](https://github.com/petervanderdoes/gitflow-avh).
+The AVH Edition of the git extensions that provides high-level repository operations for [Vincent Driessen's branching model](https://nvie.com/posts/a-successful-git-branching-model/).
+
+To use it, add `git-flow-avh` to the plugins array in your zshrc file:
+
+```zsh
+plugins=(... git-flow-avh)
+```
+
+## Requirements
+
+1. The git-flow tool has to be [installed](https://github.com/petervanderdoes/gitflow-avh#installing-git-flow)
+   separately.
+
+2. You have to use zsh's git completion instead of the git project's git completion. This is typically
+   done by default so you don't need to do anything else. If you installed git with Homebrew you
+   might have to uninstall the git completion it's bundled with.
diff --git a/plugins/git-flow-avh/git-flow-avh.plugin.zsh b/plugins/git-flow-avh/git-flow-avh.plugin.zsh
index db8b5ff89..860ca55c5 100644
--- a/plugins/git-flow-avh/git-flow-avh.plugin.zsh
+++ b/plugins/git-flow-avh/git-flow-avh.plugin.zsh
@@ -1,25 +1,3 @@
-#!zsh
-#
-# Installation
-# ------------
-#
-# To achieve git-flow 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-flow-completion.zsh) and put the following line in
-#        your .zshrc:
-#
-#            source ~/.git-flow-completion.zsh
-#
-#     c. Or, use this file as a oh-my-zsh plugin.
-#
-
 _git-flow ()
 {
     local curcontext="$curcontext" state line
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'
diff --git a/plugins/grails/README.md b/plugins/grails/README.md
new file mode 100644
index 000000000..6bf2ac1e6
--- /dev/null
+++ b/plugins/grails/README.md
@@ -0,0 +1,16 @@
+# Grails plugin
+
+Adds tab-completion of [Grails](https://grails.org/) script names to the command line use of grails.
+
+To use it, add `grails` to the plugins array in your zshrc file:
+
+```zsh
+plugins=(... grails)
+```
+
+It looks for scripts in the following paths:
+
+- `$GRAILS_HOME/scripts`
+- `~/.grails/scripts`
+- `./scripts`
+- `./plugins/*/scripts`
diff --git a/plugins/kops/README.md b/plugins/kops/README.md
new file mode 100644
index 000000000..5d9b5f8d6
--- /dev/null
+++ b/plugins/kops/README.md
@@ -0,0 +1,12 @@
+# kops
+
+This plugin provides completion for [kops](https://github.com/kubernetes/kops) (Kubernetes Operations),
+the command line interface to get a production grade Kubernetes cluster up and running.
+
+To use it, add `kops` to the plugins array in your zshrc file.
+
+```
+plugins=(... kops)
+```
+
+**Author:** [@nmrony](https://github.com/nmrony)
diff --git a/plugins/kops/kops.plugin.zsh b/plugins/kops/kops.plugin.zsh
index f707f3aff..0c38ce2df 100644
--- a/plugins/kops/kops.plugin.zsh
+++ b/plugins/kops/kops.plugin.zsh
@@ -1,9 +1,3 @@
-# Autocompletion for kops (Kubernetes Operations),
-# the command line interface to get a production grade
-# Kubernetes cluster up and running
-
-# Author: https://github.com/nmrony
-
 if [ $commands[kops] ]; then
   source <(kops completion zsh)
 fi
diff --git a/plugins/minikube/README.md b/plugins/minikube/README.md
new file mode 100644
index 000000000..eb2dd9b46
--- /dev/null
+++ b/plugins/minikube/README.md
@@ -0,0 +1,9 @@
+# minikube
+
+This plugin provides completion for [minikube](https://github.com/kubernetes/minikube).
+
+To use it, add `minikube` to the plugins array in your zshrc file.
+
+```
+plugins=(... minikube)
+```