diff --git a/layers/+checkers/spell-checking/README.org b/layers/+checkers/spell-checking/README.org
index 5984a31d0..2b60b6e70 100644
--- a/layers/+checkers/spell-checking/README.org
+++ b/layers/+checkers/spell-checking/README.org
@@ -2,17 +2,27 @@
 
 * Table of Contents                                         :TOC_4_gh:noexport:
 - [[#description][Description]]
+  - [[#features][Features:]]
 - [[#install][Install]]
   - [[#layer][Layer]]
   - [[#spell-checker-configuration][Spell Checker Configuration]]
   - [[#disabling-by-default][Disabling by default]]
   - [[#enabling-auto-dictionary-mode][Enabling auto-dictionary-mode]]
+  - [[#enabling-multi-dictionary-support-with-hunspell][Enabling multi-dictionary support with hunspell]]
   - [[#enable-auto-completion-popup][Enable auto-completion popup]]
 - [[#key-bindings][Key Bindings]]
+- [[#known-issues][Known issues]]
 
 * Description
 This layer provides spell checking using [[http://www-sop.inria.fr/members/Manuel.Serrano/flyspell/flyspell.html][Flyspell]] and [[https://github.com/nschum/auto-dictionary-mode][auto-dictionary-mode]].
 
+** Features:
+ - Buffer-wide spell checking via external command (ispell, hunspell, aspell)
+ - Spell as you type
+ - Optional corrections popup controlled with enable-flyspell-auto-completion
+   variable.
+ - Auto dictionary mode for some languages.
+
 * Install
 ** Layer
 To use this configuration layer, add it to your =~/.spacemacs=. You will need to
@@ -79,6 +89,26 @@ currently supported language:
 | spanish           |
 | swedish           |
 
+** Enabling multi-dictionary support with hunspell
+If your language is not supported by auto-dictionary feature or you author
+multi-lingual documents you might be compeled to use hunspell's multi-dictionary
+mode. For example to enable it for pl_PL and en_GB dictionaries you could put
+following code in your dotspacemacs/user-config section in your configuration
+file:
+
+#+BEGIN_SRC emacs-lisp
+(with-eval-after-load "ispell"
+    (setq ispell-program-name "hunspell")
+    ;; ispell-set-spellchecker-params has to be called
+    ;; before ispell-hunspell-add-multi-dic will work
+    (ispell-set-spellchecker-params)
+    (ispell-hunspell-add-multi-dic "pl_PL,en_GB")
+    (setq ispell-dictionary "pl_PL,en_GB"))
+#+END_SRC
+
+One caveat is you need quite modern ispell.el for above to work. It's been
+tested with version coming from Emacs 25.2 repository.
+
 ** Enable auto-completion popup
 To enable auto-completion popup when the point is idle on a misspelled word
 set the layer variable =enable-flyspell-auto-completion= to t:
@@ -97,3 +127,9 @@ set the layer variable =enable-flyspell-auto-completion= to t:
 | ~SPC S d~   | change dictionary        |
 | ~SPC S n~   | flyspell goto next error |
 | ~SPC t S~   | toggle flyspell          |
+
+* Known issues
+Vim-empty-lines layer seems incompatible with spell-checking inside org-mode. If
+you experience "Args out of range" error message when invoking ~SPC S c~ inside
+org-mode buffer then check if you don't have vim-empty-lines layer enabled and
+disable it.