diff --git a/core/templates/layer-README.template b/core/templates/layer-README.template
index 67fb962c1..0b82f2a36 100644
--- a/core/templates/layer-README.template
+++ b/core/templates/layer-README.template
@@ -11,11 +11,10 @@
      - [[#key-bindings][Key bindings]]
 
 ** Description
-
-This layer does wondeful things: - thing01
+This layer does wonderful things:
+  - thing01
 
 ** Install
-
 To use this contribution add it to your =~/.spacemacs=
 
 #+begin_src emacs-lisp
diff --git a/doc/CONTRIBUTE.org b/doc/CONTRIBUTE.org
index bd2cfbba2..6e47d6faf 100644
--- a/doc/CONTRIBUTE.org
+++ b/doc/CONTRIBUTE.org
@@ -52,14 +52,14 @@ Contributed configuration layers are stored in the =contrib= folder. The
 layers in. For example a layer for a language would go in the
 =contrib/!lang= folder.
 
-It is recommended to join a =README.md= file with your layer: - ideally
-this file should document the packages of your layer as well as the key
-bindings associated with them, - a template is provided in
-=~/.emacs.d/core/templates/layer-README.template=, use it as much as
-possible, - another good practice is to start from the =README.md= of an
-existing layer, - if a logo exists for the layer you can
-add it at the top of the =README.md= before the TOC. The maximum
-recommended height is 200 pixels.
+It is recommended to join a =README.org= file with your layer:
+  - ideally this file should document the packages of your layer as well as the
+    key bindings associated with them
+  - a template is provided in =~/.emacs.d/core/templates/layer-README.template=,
+    use it as much as possible
+  - another good practice is to start from the =README.org= of an existing layer
+  - if a logo exists for the layer you can add it at the top of the =README.org=
+    before the TOC. The maximum recommended height is 200 pixels.
 
 ** Submitting a banner
 The startup banner is by default randomly chosen among a pool of banners
diff --git a/doc/CONVENTIONS.org b/doc/CONVENTIONS.org
index 0a1cf1de0..b49a999d9 100644
--- a/doc/CONVENTIONS.org
+++ b/doc/CONVENTIONS.org
@@ -33,6 +33,8 @@
              - [[#language-specific][Language specific]]
          - [[#refactoring][Refactoring]]
          - [[#help-or-documentation][Help or Documentation]]
+     - [[#writing-documentation][Writing documentation]]
+         - [[#spacing-in-documentation][Spacing in documentation]]
 
 ** Code guidelines
 *** Spacemacs core and layer
@@ -302,3 +304,17 @@ as an help command.
 |---------+------------------------------------|
 | ~m h h~ | documentation of thing under point |
 | ~m h r~ | documentation of selected region   |
+
+** Writing documentation
+Spacemacs provides an example layer =README.org= file in
+=~/.emacs.d/core/templates/layer-README.template=.
+
+*** Spacing in documentation
+Spacemacs tries to keep the documentation consistent between all layers by
+providing some rules for spacing:
+  - After each header, you should not add an empty line
+    - *Exception*: If the first item under the header is a table, add an empty
+      line after it
+  - At the end of each header node, there should be an empty line
+  - Note: Many layer =READMEs= do not follow this convention yet. Please fix
+    them if you can.