diff --git a/docs/README.txt b/docs/README.txt
index 6205b2ca4d96ce0aa61fa70c62e8bfbc16525376..5145c53c40ebc60f1a709a52feab53d0c457c068 100644
--- a/docs/README.txt
+++ b/docs/README.txt
@@ -1,18 +1 @@
-This is the MOOSE documentation directory. The documentation is grouped into
-the following directories:
-
-    - user: This is for anyone wishing to learn/use MOOSE.
-            This part of the documentation is encoded in Markdown format.
-    - developer: If you wish to learn about MOOSE code, go here.
-    - doxygen: Source code documentation generation.
-    - markdown: This contains a quick introduction to Markdown itself.
-    - images: These are images that are included in the user and developer
-              documentation.
-
---------------------------------------------------------------------------------
-N.B.: This text file has Windows-style line endings (CR/LF) for easy
-viewing in Windows. We will try to keep the other text files here
-Windows-compatible (e.g.: *.markdown files), but we may slip.
-If you have difficulty viewing them in Notepad, try the inbuilt Wordpad
-editor, or better still, download a good text editor like Notepad++ or Geany.
---------------------------------------------------------------------------------
+The source code of documentation is ./source directory. 
diff --git a/docs/readthedocs-pip-requirements.txt b/docs/readthedocs-pip-requirements.txt
index a2954e3184d712187766018da8c9007e86d424a7..e05848ed60ba27146c6098f4f86804f9d9df8a24 100644
--- a/docs/readthedocs-pip-requirements.txt
+++ b/docs/readthedocs-pip-requirements.txt
@@ -1 +1,2 @@
 numpydoc
+mock
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 329de82eb5c8b07d3f4a6b4debb98497c03a576d..92521adc5c93de779b7978b25ed0039a52b9ee96 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -137,16 +137,6 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 # of the sidebar.
 html_logo = 'images/moose_logo.png'
 
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
@@ -270,7 +260,15 @@ texinfo_domain_indices = True
 numpydoc_show_class_members = False
 
 # autodoc options to mock MOOSE module
-autodoc_mock_imports = [ 'numpy' , 'moose.sbml' , 'moose.genesis' , 'moose.LIF' , 'moogli.extensions.moose' , 'extensions.moose', 'moose' , 'moose.SBML' , 'pylab' , 'moose.genesis' , 'datetime' , 'getpass' , 'h5py' , 'matplotlib' , 'squid' , 'PyQt4' , 'moogli' , 'moose.utils' , 'math' , 'SquidAxon' , '_moogli' , 'XRRRates' , 'neuroml.NeuroML' ,'neuroml' , 'rdesigneur' , 'pyplot' , 'gnuplot' , 'cm' , 'matplotlib.pyplot' , 'matplotlib.image' , 'matplotlib.cm' , 'shapes' , 'chemUtil.add_Delete_ChemicalSolver' ]
+autodoc_mock_imports = [ 'numpy' , 'moose.sbml' , 'moose.genesis' , 'moose.LIF'
+        , 'moogli.extensions.moose' , 'extensions.moose', 'moose' , 'moose.SBML' 
+        , 'pylab' , 'moose.genesis' , 'datetime' , 'getpass' , 'h5py' 
+        , 'matplotlib' , 'squid' , 'PyQt4' , 'moogli' , 'moose.utils' 
+        , 'math' , 'SquidAxon' , '_moogli' , 'XRRRates' , 'neuroml.NeuroML' 
+        ,'neuroml' , 'rdesigneur' , 'pyplot' , 'gnuplot' , 'cm'
+        , 'matplotlib.pyplot' , 'matplotlib.image' , 'matplotlib.cm' , 'shapes' 
+        , 'chemUtil.add_Delete_ChemicalSolver' 
+        ]
 
 #include reference files
 exclude_patterns = ['/docs/source/user/py/references/*.rst']
diff --git a/docs/source/install/install.rst b/docs/source/install/install.rst
index d0aafce9140c22f428ef0ed7bc69e6e9cc619b4a..a2dd15f010a6fcac3f1f46d6472801183297d180 100644
--- a/docs/source/install/install.rst
+++ b/docs/source/install/install.rst
@@ -5,7 +5,7 @@ Linux
 ^^^^^^
 
 We recommend that you use our repositories hosted at `Open Build Service
-<http://build.opensuse.org>`_.  We have packages for the following distributions
+<https://build.opensuse.org/package/show/home:moose/moose>`_.  We have packages for the following distributions
 
 - Debian 7.0, 8.0
 - Ubuntu 12.04, 14.04, 15.04, 15.10, 16.04
@@ -25,22 +25,13 @@ to pick your distribution and follow instructions.
 
 .. todo:: Packages for gentoo, Arch Linux
 
-Mac OSX
-^^^^^^^
 
-Download the ``dmg`` file from `here <https://github.com/BhallaLab/moose/releases/download/ghevar_3.0.2/Moose_3.0.2_OSX.dmg>`_.
-
-Alternatively, you can use ``homebrew`` to install ``moose``
+MacOSX support is not complete yet. Python-scripting interface can be installed on MaxOSX using ``homebrew``
 ::
 
     $ brew install homebrew/science/moose
 
 
-Windows/Cygwin
-^^^^^^^^^^^^^^
-
-Coming soon...!
-
 Building MOOSE
 --------------
 
@@ -64,13 +55,6 @@ Or,
 If you don't want lasest snapshot of ``MOOSE``, you can download other released
 versions from `here <`https://github.com/BhallaLab/moose/releases>`_.
 
-Once you have downloaded the repository, ::
-
-    $ cd moose
-    $ git submodule update --init; git pull
-                      or
-    $ sudo -E ./update-repository     # This script updates the repository and its subrepositories recursively, located in moose folder
-
 Install dependencies
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -125,20 +109,6 @@ On ``OpenSUSE``
 build moose
 ^^^^^^^^^^^
 
-Method 1: Using Makefile
-""""""""""""""""""""""""
-
-.. code-block:: bash
-
-    $ cd moose-core
-    $ make
-    $ export PYTHONPATH="/homedir/moose-core/python"
-               or
-    $ ./build-moose-core #builds moose and sets the pythonpath in local_site_package_directory
-
-Method 2: Using cmake
-"""""""""""""""""""""
-
 .. code-block:: bash
 
    $ cd /to/moose/source/code
@@ -147,6 +117,7 @@ Method 2: Using cmake
    $ cmake  ..
    $ make
    $ ctest --output-on-failure  # optional
+   $ sudo make install 
 
 This will build pyMOOSE (MOOSE's python extention), `ctest` will run few tests to
 check if build process was successful.
diff --git a/docs/source/user/py/introduction/changes/index.rst b/docs/source/user/py/introduction/changes/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9a167f14daf7633c581babd2cd82e2b452ad0900
--- /dev/null
+++ b/docs/source/user/py/introduction/changes/index.rst
@@ -0,0 +1,4 @@
+Changes
+=======
+
+.. todo:: collect changes from OBS.
diff --git a/docs/source/user/py/introduction/index.rst b/docs/source/user/py/introduction/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b55005ae6f816a5f00fdf23c1bad96f77bd1f681
--- /dev/null
+++ b/docs/source/user/py/introduction/index.rst
@@ -0,0 +1,9 @@
+Introduction
+============
+
+.. toctree::
+
+   install/index
+   release_notes/index
+   changes/index
+   known_issues/index
diff --git a/docs/source/user/py/introduction/install/index.rst b/docs/source/user/py/introduction/install/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..888aede83b0df0716bc7b784444ac2f5e914d210
--- /dev/null
+++ b/docs/source/user/py/introduction/install/index.rst
@@ -0,0 +1,208 @@
+Installation
+============
+
+Use pre-built packages
+----------------------
+
+Linux
+^^^^^
+
+We recommend that you use our repositories hosted at `Open Build Service
+<http://build.opensuse.org>`_.  We have packages for the following distributions
+
+- Debian 7.0, 8.0
+- Ubuntu 12.04, 14.04, 15.04, 15.10, 16.04 
+- CentOS 6, 7 
+- Fedora 20, 21, 22, 23
+- OpenSUSE 13.1, 13.2, Factory ARM, Leap 42.1, Tumbleweed
+- SLE 12, 12 SP1
+- RHEL 7
+- Scientific Linux 7
+  
+Visit `this page
+<https://software.opensuse.org/download.html?project=home:moose&package=moose>`_
+pick you distribution and follow instructions.
+
+.. note:: 
+    ``moogli`` (tool to visualize network activity) is not available for CentOS-6. 
+
+.. raw:: html
+    <iframe
+    src="http://software.opensuse.org/download/package.iframe?project=moose&package=moose"></iframe>
+
+.. todo:: Packages for gentoo, Arch Linux
+
+
+Mac OSX
+^^^^^^
+
+:strike:`Download the ``dmg`` file from `here <https://github.com/BhallaLab/moose/releases/download/ghevar_3.0.2/Moose_3.0.2_OSX.dmg>`_.` We no longer build `dmg` files. 
+
+
+On MacOSX, `MOOSE` is available via `homebrew <https://brew.sh>`_.
+::
+    $ brew install homebrew/science/moose
+
+
+Windows/Cygwin
+^^^^^^^^^^^^^^
+
+Building MOOSE 
+--------------
+
+In case your distribution is not listed on `our repository page
+<https://software.opensuse.org/download.html?project=home:moose&package=moose>`_
+, or if you want to build the lastest development code, read on.
+
+First, you need to get the source code. You can use ``git`` (clone the 
+repository) or download snapshot of github repo by clicking on `this link
+<https://github.com/BhallaLab/moose/archive/master.zip>`_.::
+    $ git clone https://github.com/BhallaLab/moose
+
+Or,
+::
+    $ wget https://github.com/BhallaLab/moose/archive/master.zip
+    $ unzip master.zip
+
+If you don't want lasest snapshot of ``MOOSE``, you can download other released
+versions from here `https://github.com/BhallaLab/moose/releases`.
+
+Install dependencies
+~~~~~~~~~~~~~~~~~~~
+
+Next, you need to install required dependencies. Depending on your OS, names of 
+following packages may vary.
+
+- cmake (version 2.8 or higher)
+- gsl-1.16 or higher `download <ftp://ftp.gnu.org/gnu/gsl/>`_.
+- libhdf5 development package e.g. `libhdf5-serial-dev` or `libhdf5-devel`
+- python development package e.g. `python-dev` or `python-devel`
+- numpy e.g. `python-numpy` or `numpy`
+
+Most of the dependencies can be installed using package manager.
+
+On ``Debian/Ubuntu`` 
+::
+    $ sudo apt-get install libhdf5-dev cmake libgsl0-dev libpython-dev python-numpy 
+
+.. note::
+    Ubuntu 12.04 does not have required version of ``gsl`` (required 1.16 or
+    higher, available 1.15). On Ubuntu 16.04, package name is ``libgsl-dev``. 
+
+On ``CentOS/Fedora/RHEL/Scientific Linux``  
+::
+    $ sudo yum install hdf5-devel cmake libgsl-dev python-devel python-numpy
+
+On ``OpenSUSE``  
+::
+    $ sudo zypper install hdf5-devel cmake libgsl-dev python-devel python-numpy 
+
+Now use `cmake` to build moose
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. codeblock:: bash
+    $ cd /to/moose/source/code
+    $ mkdir _build
+    $ cd _build 
+    $ cmake  ..
+    $ make 
+    $ ctest --output-on-failure  # optional
+
+This will build pyMOOSE (MOOSE's python extention), `ctest` will run few tests to
+check if build process was successful.
+
+.. note::
+    To install MOOSE into non-standard directory, pass additional argument
+    `-DCMAKE_INSTALL_PREFIX=path/to/install/dir` to cmake 
+    ::
+        $ cmake -DCMAKE_INSTALL_PREFIC=$HOME/.local .. 
+
+    To use different version of python 
+    ::
+        $ cmake -DPYTHON_EXECUTABLE=/opt/python3/bin/python3 ..
+
+After that installation is pretty easy 
+::
+    $ sudo make install
+
+If everything went fine, you should be able to import moose in python shell.
+
+.. code-block:: python
+    import moose
+
+
+Graphical User Interface (GUI)
+------------------------------
+
+You can get the source of ``moose-gui`` from `here
+<https://github.com/BhallaLab/moose-gui>`_. You can download it either by
+clicking on `this link <https://github.com/BhallaLab/moose-gui/archive/master.zip>`_ 
+or by using ``git`` ::
+    $ git clone https://github.com/BhallaLab/moose-gui
+
+To be able to launch ``moose-gui``, you need to install some more packages
+
+- matplotlib 
+- python-qt4
+
+On ``Ubuntu/Debian``, these can be installed with
+::
+    $ sudo apt-get install python-matplotlib python-qt4
+
+On ``CentOS/Fedora/RHEL``
+::
+    $ sudo yum install python-matplotlib python-qt4 
+
+Now you can fire up the GUI
+::
+    $ cd /to/moose-gui
+    $ python mgui.py 
+
+.. note:: 
+    If you have installed ``moose`` package, then GUI is launched by
+    running following commnad::
+        $ moose
+
+Building moogli 
+---------------
+
+``moogli`` is subproject of ``MOOSE`` for visualizing models. More details can
+be found `here <http://moose.ncbs.res.in/moogli>`_.
+
+`Moogli` is part of `moose` package. Building moogli can be tricky because of 
+multiple depednecies it has.
+
+
+To get the latest source code of ``moogli``, click on `this link <https://github.com/BhallaLab/moogli/archive/master.zip>`_.
+
+Moogli depends on ``OpenSceneGraph`` (version 3.2.0 or higher) which may not 
+be easily available for your operating system.
+For this reason, we distribute required ``OpenSceneGraph`` with ``moogli``
+source code.
+
+Depending on distribution of your operating system, you would need following
+packages to be installed.
+
+On ``Ubuntu/Debian``
+::
+    $ sudo apt-get install python-qt4-dev python-qt4-gl python-sip-dev libqt4-dev 
+
+On ``Fedora/CentOS/RHEL``
+::
+    $ sudo yum install sip-devel PyQt4-devel qt4-devel libjpeg-devel PyQt4 
+
+On ``openSUSE``
+::
+    $ sudo zypper install python-sip python-qt4-devel libqt4-devel python-qt4
+
+After this, building and installing ``moogli`` should be as simple as
+::
+    $ cd /path/to/moogli
+    $ mkdir _build
+    $ cd _build
+    $ cmake ..
+    $ make 
+    $ sudo make install
+
+If you run into troubles, please report it on our `github repository
+<https://github.com/BhallaLab/moose/issues>`_.
diff --git a/docs/source/user/py/introduction/known_issues/index.rst b/docs/source/user/py/introduction/known_issues/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0ad5cdd653f187c374b75e0d605f748d2e3c8ea9
--- /dev/null
+++ b/docs/source/user/py/introduction/known_issues/index.rst
@@ -0,0 +1,9 @@
+Known issues
+============
+
+Full report can be found at the following places
+
+- Related to build, packages and documentation `https://github.com/BhallaLab/moose/issues`
+- Related to python interface of MOOSE `https://github.com/BhallaLab/moose-core/issues`
+- Related to MOOSE GUI `https://github.com/BhallaLab/moose-gui/issues`
+- Related to ``moogli`` `https://github.com/BhallaLab/moogli/issues`
diff --git a/docs/source/user/py/introduction/release_notes/index.rst b/docs/source/user/py/introduction/release_notes/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..862216e95c1d42e9c53d4f176e75ffdfe2987165
--- /dev/null
+++ b/docs/source/user/py/introduction/release_notes/index.rst
@@ -0,0 +1,4 @@
+Release Notes
+============
+
+.. todo:: Collect release notes from github.