diff --git a/layers/+completion/ivy/README.org b/layers/+completion/ivy/README.org
new file mode 100644
index 000000000..299883baa
--- /dev/null
+++ b/layers/+completion/ivy/README.org
@@ -0,0 +1,57 @@
+#+TITLE: Ivy layer
+
+* Table of Contents                                         :TOC_4_gh:noexport:
+ - [[#description][Description]]
+ - [[#install][Install]]
+ - [[#configuration][Configuration]]
+ - [[#key-bindings][Key Bindings]]
+   - [[#transient-state][Transient state]]
+
+* Description
+This layer enables Ivy for completion. It will replace the default completion by [[https://github.com/emacs-helm/helm][Helm]].
+
+These completion systems are the central control towers of Spacemacs, they are
+used to manage buffers, projects, search results, configuration layers, toggles
+and more...
+
+Mastering your choice of completion system will make you a Spacemacs power user.
+
+* Install
+To use this configuration layer, add it to your =~/.spacemacs=. You will need to
+add =ivy= to the existing =dotspacemacs-configuration-layers= list in this
+file.
+
+* Configuration
+You can customize ivy with the following variables:
+
+- =ivy-wrap= Whether C-n and C-p should wrap-around when at the the first or last candidate. The default value is nil.
+- =ivy-extra-directories= Setting this to nil hides . and .. directories from file name completion. You can still go up a directory up by ~DEL~. The default value is ("../", "./").
+- =ivy-use-virtual-buffers= Add bookmarks and recent files to buffer completion menu. The Spacemacs default is t.
+- =ivy-height= The height of the minibuffer. The Spacemacs default is 15.
+
+* Key Bindings
+If you choose =ivy= as completion system, make sure to read the [[http://oremacs.com/swiper/][official manual]]. In
+case you don't want to read everything, at least familiarise with [[http://oremacs.com/swiper/#minibuffer-key-bindings][minibuffer key
+bindings]]. Some useful key bindings are presented in the following table.
+
+| Key Binding | Description                                                                                          |
+|-------------+------------------------------------------------------------------------------------------------------|
+| ~RET~       | call default action on current candidate                                                             |
+| ~M-RET~     | the same as ~RET~ but doesn't close completion minibuffer                                            |
+| ~C-M-j~     | use current input immediately (this can be used to create a new file in Find File)                   |
+| ~tab~       | complete partially                                                                                   |
+| ~M-o~       | show the list of valid actions on current candidate (then press any of described keys to execute it) |
+| ~C-M-o~     | the same as ~M-o~ but doesn't close completion minibuffer                                            |
+| ~C-'~       | use avy to quickly select completion on current page (sometimes faster than using arrows)            |
+| ~<ESC>~     | close minibuffer                                                                                     |
+
+** Transient state
+Press ~M-SPC~ anytime in Ivy to get into the transient state.
+
+| Key Binding | Description                                             |
+|-------------+---------------------------------------------------------|
+| ~j~         | select next candidate                                   |
+| ~k~         | select previous candidate                               |
+| ~d~         | call default action on candidate                        |
+| ~g~         | the same as ~d~ but doesn't close completion minibuffer |
+| ~o~         | leave transient state                                   |