diff --git a/plugins/bazel/README.md b/plugins/bazel/README.md
index e5ffe6ea1..fc375d219 100644
--- a/plugins/bazel/README.md
+++ b/plugins/bazel/README.md
@@ -1,5 +1,14 @@
-## Bazel autocomplete plugin
+# Bazel plugin
 
-A copy of the completion script from the
-[bazelbuild/bazel](https://github.com/bazelbuild/bazel/master/scripts/zsh_completion/_bazel)
-git repo.
+This plugin adds completion for [bazel](https://bazel.build), an open-source build and
+test tool that scalably supports multi-language and multi-platform projects.
+
+To use it, add `bazel` to the plugins array in your zshrc file:
+
+```zsh
+plugins=(... bazel)
+```
+
+The plugin has a copy of [the completion script from the git repository][1].
+
+[1]: https://github.com/bazelbuild/bazel/blob/master/scripts/zsh_completion/_bazel