diff --git a/doc/source/index.rst b/doc/source/index.rst
index 7fe0befc..6715bd4f 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -19,6 +19,7 @@ Contents
    fixture
    parser
    exceptions
+   namespaces
    styleguide
    generator
    contributing
diff --git a/doc/source/namespaces.rst b/doc/source/namespaces.rst
new file mode 100644
index 00000000..6c5f32a9
--- /dev/null
+++ b/doc/source/namespaces.rst
@@ -0,0 +1,12 @@
+----------------------------------------------
+Choosing group names for configuration options
+----------------------------------------------
+
+Applications should use a meaningful name without a prefix. For Oslo
+libraries, when naming groups for configuration options using the
+name of the library itself instead of a descriptive name to help avoid
+collisions. If the library name is namespaced then use '_' as a separator
+in the group name.
+
+For example, the ``oslo.log`` library should use ``oslo_log`` as the
+group name.