Add more to configuration documentation

1 files changed, 49 insertions, 0 deletions

diff --git a/docs/source/user/configuration.rst b/docs/source/user/configuration.rst
index c3f3e2c..1e51e0a 100644
--- a/docs/source/user/configuration.rst
+++ b/docs/source/user/configuration.rst
@@ -27,3 +27,52 @@ Presently, Flake8 supports storing its configuration in the following places:
 - Your top-level user directory
 
 - In your project in one of ``setup.cfg``, ``tox.ini``, or ``.flake8``.
+
+
+"User" Configuration
+--------------------
+
+Flake8 allows a user to use "global" configuration file to store preferences.
+The user configuration file is expected to be stored somewhere in the user's
+"home" directory.
+
+- On Windows the "home" directory will be something like
+  ``C:\\Users\sigmavirus24``, a.k.a, ``~\``.
+
+- On Linux and other Unix like systems (including OS X) we will look in
+  ``~/``.
+
+Note that Flake8 looks for ``~\.flake8`` on Windows and ``~/.config/flake8``
+on Linux and other Unix systems.
+
+
+Project Configuration
+---------------------
+
+Flake8 is written with the understanding that people organize projects into
+sub-directories. Let's take for example Flake8's own project structure
+
+.. code::
+
+    flake8
+    ├── docs
+    │   ├── build
+    │   └── source
+    │       ├── _static
+    │       ├── _templates
+    │       ├── dev
+    │       ├── internal
+    │       └── user
+    ├── flake8
+    │   ├── formatting
+    │   ├── main
+    │   ├── options
+    │   └── plugins
+    └── tests
+        ├── fixtures
+        │   └── config_files
+        ├── integration
+        └── unit
+
+In the top-level ``flake8`` directory (which contains ``docs``, ``flake8``,
+and ``tests``) there's also ``tox.ini`` and ``setup.cfg`` files.