diff --git a/plugins/mvn/README.md b/plugins/mvn/README.md
index 3f08c56d8..88f5be8ba 100644
--- a/plugins/mvn/README.md
+++ b/plugins/mvn/README.md
@@ -1,7 +1,7 @@
-## Introduction
+# mvn plugin
 
-The [mvn plugin](https://github.com/robbyrussell/oh-my-zsh/tree/master/plugins/mvn) provides many
-[useful aliases](#aliases) as well as completion for the `mvn` command.
+The mvn plugin provides many [useful aliases](#aliases) as well as completion for
+the [Apache Maven](https://maven.apache.org/) command (`mvn`).
 
 Enable it by adding `mvn` to the plugins array in your zshrc file:
 ```zsh
@@ -10,7 +10,7 @@ plugins=(... mvn)
 
 ## Aliases
 
-The plugin aliases mvn to a either calls `mvnw` ([Maven Wrapper](https://github.com/takari/maven-wrapper))
+The plugin aliases mvn to a function that calls `mvnw` (the [Maven Wrapper](https://github.com/takari/maven-wrapper))
 if it's found, or the mvn command otherwise.
 
 | Alias                | Command                                         |
@@ -46,9 +46,13 @@ if it's found, or the mvn command otherwise.
 
 ## mvn-color
 
-It's a function that wraps the mvn command to colorize it's output. Since Maven 3.5.0
-the mvn command adds colored output, so this function will be soon removed from the
-plugin.
+It's a function that wraps the mvn command to colorize it's output. You can use it in place
+of the `mvn` command. For example: instead of `mvn test`, use `mvn-color test`.
 
-It also has a bug where it won't print when mvn prompts for user input, _e.g._ when
-using `archetype:generate`. See [#5052](https://github.com/robbyrussell/oh-my-zsh/issues/5052).
+Since [Maven 3.5.0](https://maven.apache.org/docs/3.5.0/release-notes.html) the mvn command
+has colored output, so this function will be soon removed from the plugin.
+
+### Known bugs
+
+It has a bug where it will swallow mvn prompts for user input, _e.g._ when using
+`archetype:generate`. See [#5052](https://github.com/robbyrussell/oh-my-zsh/issues/5052).