diff --git a/doc/source/contributing.rst b/doc/source/contributor/contributing.rst
similarity index 100%
rename from doc/source/contributing.rst
rename to doc/source/contributor/contributing.rst
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
new file mode 100644
index 00000000..a28f816a
--- /dev/null
+++ b/doc/source/contributor/index.rst
@@ -0,0 +1,8 @@
+Contributor Guide
+=================
+
+.. toctree::
+  :maxdepth: 2
+  :includehidden:
+
+  contributing
diff --git a/doc/source/index.rst b/doc/source/index.rst
index dea00566..756f1f6b 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -6,20 +6,22 @@
 Welcome to python-tempestconf's documentation!
 ========================================================
 
+python-tempestconf is a tool for automatic generation of tempest configuration
+based on user's cloud.
+
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
-   readme
-   installation
-   usage
-   contributing
+   overview
+   install/index
+   user/index
+   contributor/index
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
new file mode 100644
index 00000000..3dc47361
--- /dev/null
+++ b/doc/source/install/index.rst
@@ -0,0 +1,8 @@
+Install Guide
+=============
+
+.. toctree::
+  :maxdepth: 2
+  :includehidden:
+
+  installation
diff --git a/doc/source/installation.rst b/doc/source/install/installation.rst
similarity index 100%
rename from doc/source/installation.rst
rename to doc/source/install/installation.rst
diff --git a/doc/source/overview.rst b/doc/source/overview.rst
new file mode 100644
index 00000000..0cc905a7
--- /dev/null
+++ b/doc/source/overview.rst
@@ -0,0 +1,14 @@
+========
+Overview
+========
+
+python-tempestconf will automatically generate the tempest configuration
+based on your cloud.
+
+-  Free software: Apache license
+-  Documentation:
+   http://git.openstack.org/cgit/openstack/python-tempestconf/tree/README.rst
+-  Source: https://git.openstack.org/openstack/python-tempestconf
+-  Bugs: https://storyboard.openstack.org/#!/project/912
+-  Release notes: https://docs.openstack.org/releasenotes/python-tempestconf
+
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
deleted file mode 100644
index a6210d3d..00000000
--- a/doc/source/readme.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../README.rst
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
deleted file mode 100644
index 79675e1b..00000000
--- a/doc/source/usage.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-========
-Usage
-========
-
-To use python-tempestconf in a project::
-
-    import tempest_config
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
new file mode 100644
index 00000000..03dde542
--- /dev/null
+++ b/doc/source/user/index.rst
@@ -0,0 +1,8 @@
+Usage
+=====
+
+.. toctree::
+  :maxdepth: 2
+  :includehidden:
+
+  usage
diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst
new file mode 100644
index 00000000..788abd6f
--- /dev/null
+++ b/doc/source/user/usage.rst
@@ -0,0 +1,99 @@
+========
+Usage
+========
+
+To use python-tempestconf in a project::
+
+    import tempest_config
+
+Git
+---
+
+1. Clone and change to the directory:
+
+.. code-block:: shell-session
+
+    $ git clone https://git.openstack.org/openstack/python-tempestconf
+    $ cd python-tempestconf
+
+2. Create virtual environment using virtualenv:
+
+.. code-block:: shell-session
+
+    $ virtualenv .venv
+    $ source .venv/bin/activate
+
+3. Source the newly created virtual environment and install
+   requirements:
+
+.. code-block:: shell-session
+
+    (.venv) $ pip install -r requirements.txt
+    (.venv) $ pip install -r test-requirements.txt
+
+4. Source cloud credentials, for example:
+
+.. code-block:: shell-session
+
+    (py27) $ source cloudrc
+
+5. Run python-tempestconf to generate tempest configuration file:
+
+.. code-block:: shell-session
+
+    (py27) $ python config_tempest/config_tempest.py --debug identity.uri $OS_AUTH_URL \
+                identity.admin_password  $OS_PASSWORD --create
+
+After this, ``./etc/tempest.conf`` is generated.
+
+RPM Installation (RDO)
+----------------------
+
+1. python-tempestconf is installed together with openstack-tempest, as
+   a new dependency (starting from the Ocata release)
+
+.. code-block:: shell-session
+
+    # yum install openstack-tempest
+
+2. Source cloud credentials, initialize tempest and run the discovery
+   tool:
+
+.. code-block:: shell-session
+
+    $ source cloudrc
+    $ tempest init testingdir
+    $ cd testingdir
+    $ discover-tempest-config --debug identity.uri $OS_AUTH_URL \
+          identity.admin_password  $OS_PASSWORD --create
+
+.. note::
+   In Ocata release new features were presented.
+   ``discover-tempest-config`` is the new name of the **old**
+   ``config_tempest.py`` script and it **accepts the same parameters.**
+   More about new features can be found
+   `here <https://blogs.rdoproject.org/2017/02/testing-rdo-with-tempest-new-features-in-ocata/>`__
+
+
+os-client-config support
+------------------------
+
+python-tempestconf supports `os-client-config <https://git.openstack.org/openstack/os-client-config>`__
+so instead of sourcing openstackrc files you can use clouds.yml files. Location where
+these files should be stored and syntax which is used to specify cloud.yaml files
+can be found `here <https://docs.openstack.org/os-client-config/latest/user/configuration.html#config-files>`__
+
+In case of git usage:
+
+.. code-block:: shell-session
+
+    (py27) $ python config_tempest/config_tempest.py --debug --create --os-cloud <name of cloud>
+
+In case of RPM:
+
+.. code-block:: shell-session
+
+    $ tempest init testingdir
+    $ cd testingdir
+    $ discover-tempest-config --debug --create --os-cloud <name of cloud>
+