diff --git a/plugins/pj/README.md b/plugins/pj/README.md
new file mode 100644
index 000000000..27e5638ec
--- /dev/null
+++ b/plugins/pj/README.md
@@ -0,0 +1,45 @@
+# pj
+
+The `pj` plugin (short for `Project Jump`) allows you to define several
+folders where you store your projects, so that you can jump there directly
+by just using the name of the project directory.
+
+Original idea and code by Jan De Poorter ([@DefV](https://github.com/DefV))
+Source: https://gist.github.com/pjaspers/368394#gistcomment-1016
+
+## Usage
+
+1. Enable the `pj` plugin:
+
+   ```zsh
+   plugins=(... pj)
+   ```
+
+2. Set `$PROJECT_PATHS` in your ~/.zshrc:
+
+   ```zsh
+   PROJECT_PATHS=(~/src ~/work ~/"dir with spaces")
+   ```
+
+You can now use one of the following commands:
+
+##### `pj my-project`:
+
+`cd` to the directory named "my-project" found in one of the `$PROJECT_PATHS`
+directories. If there are several directories named the same, the first one
+to appear in `$PROJECT_PATHS` has preference.
+
+For example:
+```zsh
+PROJECT_PATHS=(~/code ~/work)
+$ ls ~/code    # ~/code/blog ~/code/react
+$ ls ~/work    # ~/work/blog ~/work/project
+$ pj blog      # <-- will cd to ~/code/blog
+```
+
+##### `pjo my-project`
+
+Open the project directory with your defined `$EDITOR`. This follows the same
+directory rules as the `pj` command above.
+
+Note: `pjo` is an alias of `pj open`.
diff --git a/plugins/pj/pj.plugin.zsh b/plugins/pj/pj.plugin.zsh
index 1572e9363..84d0cfa65 100644
--- a/plugins/pj/pj.plugin.zsh
+++ b/plugins/pj/pj.plugin.zsh
@@ -1,49 +1,42 @@
-#!/bin/zsh
+alias pjo="pj open"
 
-#
-# Original idea by DefV (Jan De Poorter)
-# Source: https://gist.github.com/pjaspers/368394#comment-1016
-#
-# Usage:
-#  - Set `$PROJECT_PATHS` in your ~/.zshrc
-#    e.g.: PROJECT_PATHS=(~/src ~/work)
-#  - In ZSH you now can open a project directory with the command: `pj my-project`
-#    the plugin will locate the `my-project` directory in one of the $PROJECT_PATHS
-#    Also tab completion is supported.
-#  - `pjo my-project` will open the directory in $EDITOR
-# 
+pj () {
+    emulate -L zsh
 
-function pj() {
     cmd="cd"
-    file=$1
+    project=$1
 
-    if [[ "open" == "$file" ]] then
+    if [[ "open" == "$project" ]]; then
         shift
-        file=$*
-        cmd=(${(s: :)EDITOR})
+        project=$*
+        cmd=${=EDITOR}
     else
-        file=$*
+        project=$*
     fi
 
-    for project in $PROJECT_PATHS; do
-        if [[ -d $project/$file ]] then
-            $cmd "$project/$file"
-            unset project # Unset project var
+    if [[ -z "$project" ]]; then
+        echo "You have to specify a project name."
+        return
+    fi
+
+    for basedir ($PROJECT_PATHS); do
+        if [[ -d "$basedir/$project" ]]; then
+            $cmd "$basedir/$project"
             return
         fi
     done
 
-    echo "No such project $1"
+    echo "No such project '${project}'."
 }
 
-alias pjo="pj open"
+_pj () {
+    emulate -L zsh
 
-function _pj () {
-    # might be possible to improve this using glob, without the basename trick
     typeset -a projects
-    projects=($PROJECT_PATHS/*)
-    projects=$projects:t
-    _arguments "*:file:($projects)"
-}
+    for basedir ($PROJECT_PATHS); do
+        projects+=(${basedir}/*(/N))
+    done
 
+    compadd ${projects:t}
+}
 compdef _pj pj