diff --git a/README.md b/README.md
index cbbe25927..98a4a7cd3 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ dependencies as well.
   We strongly recommend you use the [latest version of OSX FUSE](http://osxfuse.github.io/).
   (See https://github.com/ipfs/go-ipfs/issues/177)
 * For more details on setting up FUSE (so that you can mount the filesystem), see the docs folder
-* Shell command completion is available by running `source misc/completion/ipfs-completion.bash`.
+* Shell command completion is available in `misc/completion/ipfs-completion.bash`. Read [docs/command-completion.md](docs/command-completion.md) to learn how to install it.
 
 
 ## Usage
diff --git a/docs/command-completion.md b/docs/command-completion.md
new file mode 100644
index 000000000..7a7ca5d0c
--- /dev/null
+++ b/docs/command-completion.md
@@ -0,0 +1,21 @@
+Command Completion
+==================
+
+Shell command completion is provided by the script at 
+`/misc/completion/ipfs-completion.bash`.
+
+The simplest way to see it working is to run 
+`source misc/completion/ipfs-completion.bash` straight from your shell. This
+is only temporary and to fully enable it, you'll have to follow one of the steps
+below.
+
+Linux
+-----
+### Bash
+
+For bash, completion can be enabled in a couple of ways. One is to add the line
+`source $GOPATH/src/github.com/ipfs/go-ipfs/misc/completion/ipfs-completion.bash` 
+into your `~/.bash_completion`. It will automatically be loaded the next time 
+bash is loaded.
+To enable ipfs command completion globally on your system you may also 
+copy the completion script to `/etc/bash_completion.d/`.