diff --git a/README.md b/README.md
index cbbe25927564df27f8a2c0eb313ee629722e90bd..98a4a7cd382d44f2aca013e64d1400558ef2f198 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 0000000000000000000000000000000000000000..73394d41a8aaf30bd464a06551e5dd59f7bfbf06
--- /dev/null
+++ b/docs/command-completion.md
@@ -0,0 +1,29 @@
+Command Completion
+==================
+
+Shell command completion is provided by the script at 
+[/misc/completion/ipfs-completion.bash](../misc/completion/ipfs-completion.bash).
+
+
+Installation
+------------
+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.
+
+### Bash on Linux
+For bash, completion can be enabled in a couple of ways. One is to copy the 
+completion script to the directory `~/.ipfs/` and then in the file 
+`~/.bash_completion` add
+```bash
+source ~/.ipfs/ipfs-completion.bash
+```
+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/`.
+
+
+Additional References
+---------------------
+* https://www.debian-administration.org/article/316/An_introduction_to_bash_completion_part_1