Add documentation about private layers management

DOCUMENTATION.md

@@ -21,6 +21,10 @@
     - [Types of configuration layers](#types-of-configuration-layers)
     - [Submitting a configuration layer upstream](#submitting-a-configuration-layer-upstream)
     - [Example: Themes Megapack example](#example-themes-megapack-example)
+    - [Managing private configuration layers](#managing-private-configuration-layers)
+        - [Using the private directory](#using-the-private-directory)
+        - [Using an external Git repository](#using-an-external-git-repository)
+        - [Using a personal branch](#using-a-personal-branch)
 - [Dotfile Configuration](#dotfile-configuration)
     - [Installation](#installation)
     - [Content](#content)
@@ -41,6 +45,7 @@
     - [Mode-line](#mode-line)
         - [Flycheck integration](#flycheck-integration)
         - [Anzu integration](#anzu-integration)
+        - [Battery status integration](#battery-status-integration)
         - [Powerline separators](#powerline-separators)
         - [Minor Modes](#minor-modes)
 - [Base packages](#base-packages)
@@ -325,6 +330,37 @@ you can find it [here][themes-megapack].
 To install it, just add `themes-megapack` to your `~/.spacemacs`. You have now
 installed around 100 themes you are free to try with `<SPC> h t` (helm-themes).
 
+## Managing private configuration layers
+
+`Spacemacs` configuration system is flexible enough to let you manage your
+private layers in different ways.
+
+### Using the private directory
+
+Everything in the private directory is ignored by Git so it is a good place
+to store private layers. There is a huge drawback to this approach though:
+_your layers are not source controlled_.
+
+### Using an external Git repository
+
+This is the recommended way to manage your private layers.
+
+The best approach is to store all your private layers into an external Git
+repository. It is especially a good practice to store them in your `dotfiles`
+repository if you have one along with your `~/.spacemacs` file.
+
+Then you are free to symlink your layers into `~/emacs.d/private` _or_ let
+them anywhere you want and reference the parent directory in the variable
+`dotspacemacs-configuration-layer-path` of your `~/.spacemacs`.
+
+Note that you could also have a dedicated repository for all your private
+layers and then directly clone this repository in `~/.emacs.d/private`.
+
+### Using a personal branch
+
+The final main way to manage your private layers is to push them is a personal
+branch that you keep up to date with upstream `master` or `develop`.
+
 # Dotfile Configuration
 
 User configuration can be stored in your `~/.spacemacs` file.

README.md

@@ -124,11 +124,21 @@ configuration layer:
     <SPC> : config-system/create-layer RET
 
 After entering a name, a layer skeleton will be created in the [private][]
-directory. The `private` directory is ignored by Git.
+directory where you'll find the following files:
+- `packages.el` to list the elpa packages
+- `exentsions.el` for any other package that is not available in a elpa
+repository.
+
+The `private` directory is ignored by Git.
 
 To use your newly created configuration layer, add it to your `~/.spacemacs`
 file (see next section).
 
+Note that this approach leaves your layer not source controlled. To get more
+info on the different approaches to manage your layers, refer to the
+[Managing private configuration layers][manage_config] section of the
+documentation.
+
 ## Dotfile ~/.spacemacs
 
 `Spacemacs` has a convenient dotfile. You have to install it by invoking the
@@ -187,7 +197,8 @@ first.
 [screenshots]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#screenshots
 [config]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#configuration-layers
 [dotfile]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#dotfile-configuration
-[achievements]:  https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#achievements
+[manage_config]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#managing-private-configuration-layers
+[achievements]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#achievements
 [troubleshoot]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#troubleshoot
 [contrib layers]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#using-configuration-layers
 [Git support]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#working-with-git