diff --git a/README b/README
index 5389d23..383f3ec 100644
--- a/README
+++ b/README
@@ -8,3 +8,17 @@ it easier to experiment with some stuff I'd been thinking about.
 Now there's this, where I rewrote j2 back in bash. I like it. Sorry about all
 the repos , but it kind of grew this way.
 
+# maintains a jump-list of the directories you actually use
+#
+# INSTALL:
+#   * put something like this in your .bashrc:
+#     . /path/to/z.sh
+#   * cd around for a while to build up the db
+#   * PROFIT!!
+#
+# USE:
+#   * z foo     # goes to most frecent dir matching foo
+#   * z foo bar # goes to most frecent dir matching foo and bar
+#   * z -r rank # goes to highest ranked dir matching foo
+#   * z -t rank # goes to most recently accessed dir matching foo
+#   * z -l foo  # list all dirs matching foo (by frecency)
diff --git a/z.sh b/z.sh
index 05019d2..dde55c6 100644
--- a/z.sh
+++ b/z.sh
@@ -1,6 +1,19 @@
 #!/bin/bash
 
-# pure shell version of 'new j'
+# maintains a jump-list of the directories you actually use
+#
+# INSTALL:
+#   * put something like this in your .bashrc:
+#     . /path/to/z.sh
+#   * cd around for a while to build up the db
+#   * PROFIT!!
+#
+# USE:
+#   * z foo     # goes to most frecent dir matching foo
+#   * z foo bar # goes to most frecent dir matching foo and bar
+#   * z -r rank # goes to highest ranked dir matching foo
+#   * z -t rank # goes to most recently accessed dir matching foo
+#   * z -l foo  # list all dirs matching foo (by frecency)
 
 z() {
  local datafile=$HOME/.z