diff --git a/Doc/Sphinx/documentation/documentation.rst b/Doc/Sphinx/documentation/documentation.rst
index 87e9255a0bd279aa5d969ebb79fcbcc43c6d6ada..88a192e54d7073c8b07a1a815a227c679d8ea5d2 100644
--- a/Doc/Sphinx/documentation/documentation.rst
+++ b/Doc/Sphinx/documentation/documentation.rst
@@ -1,6 +1,6 @@
Documentation
-=============================
+#############################
.. toctree::
@@ -11,5 +11,14 @@ Documentation
installation/installation.rst
working_with_bornagain/working_with_bornagain.rst
python_api/python_api.rst
+
+
+.. toctree::
+ :maxdepth: 1
+
+ troubleshooting/troubleshooting.rst
+
+.. toctree::
+ :maxdepth: 1
-
\ No newline at end of file
+ faq/faq.rst
diff --git a/Doc/Sphinx/documentation/faq/faq.rst b/Doc/Sphinx/documentation/faq/faq.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0f07e563a3a3997b7937f7f41506e68039333b3c
--- /dev/null
+++ b/Doc/Sphinx/documentation/faq/faq.rst
@@ -0,0 +1,28 @@
+
+Frequently Asked Questions
+################################
+
+
+.. contents::
+ :depth: 1
+ :local:
+ :backlinks: none
+
+
+How to request the new feature?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Create feature request using `BornAgain Bug and Issue Tracker <http://apps.jcns.fz-juelich.de/redmine/projects/bornagain/issues>`_
+
+
+How to use the bug and issue tracker?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Users of the software who encounter problems during the installation
+of the framework or during the run of a simulation can use the web-based issue tracking system
+at `link <http://apps.jcns.fz-juelich.de/redmine/projects/bornagain/issues>`_
+to report a bug. The same system can be used to request new features.
+This system is open for all users in read mode, while
+submitting bug reports and feature requests are possible only after a simple registration
+procedure.
+
+
diff --git a/Doc/Sphinx/documentation/installation/installation.rst b/Doc/Sphinx/documentation/installation/installation.rst
index ed4534dd933faf7f3b7bd1c16fa0657d3afe9244..46c0ec919ea9b4ebe19db5f61a46d65d36b78f30 100644
--- a/Doc/Sphinx/documentation/installation/installation.rst
+++ b/Doc/Sphinx/documentation/installation/installation.rst
@@ -1,6 +1,6 @@
Installation instructions
-----------------------------------
+================================
BornAgain is supported under Windows, Mac OS X and Linux operating systems.
For Windows and MacOS we provide binary installer packages, for Unix flavor (MacOS included) we support build and installation from source.
diff --git a/Doc/Sphinx/documentation/installation/installation_unix.rst b/Doc/Sphinx/documentation/installation/installation_unix.rst
index 02b0802f01e8474eacdaa944ee7bd6b969f99c31..e890f07e8b4f352a0a079277e11aff35de539899 100644
--- a/Doc/Sphinx/documentation/installation/installation_unix.rst
+++ b/Doc/Sphinx/documentation/installation/installation_unix.rst
@@ -19,6 +19,6 @@ This advanced section explains in details how to build BornAgain's Graphical Use
:maxdepth: 3
installation_unix_gui.rst
-
+
\ No newline at end of file
diff --git a/Doc/Sphinx/documentation/installation/installation_unix_detailed.rst b/Doc/Sphinx/documentation/installation/installation_unix_detailed.rst
index d3d7a643b5b492348467e1d1ead0bcc64092c029..400452cdebe3872c56af53891a4c6206040ab55b 100644
--- a/Doc/Sphinx/documentation/installation/installation_unix_detailed.rst
+++ b/Doc/Sphinx/documentation/installation/installation_unix_detailed.rst
@@ -236,3 +236,4 @@ Run your first example and enjoy the first BornAgain simulation plot.
:ref:`building_gui_label`
+ :ref:`troubleshooting_label`
diff --git a/Doc/Sphinx/documentation/installation/installation_unix_gui.rst b/Doc/Sphinx/documentation/installation/installation_unix_gui.rst
index c8dda7c88a1ac91eee06841961b0a8f883c82b61..b9c20414044bd8b3cc65091d9a2b22453a8d36f7 100644
--- a/Doc/Sphinx/documentation/installation/installation_unix_gui.rst
+++ b/Doc/Sphinx/documentation/installation/installation_unix_gui.rst
@@ -129,15 +129,23 @@ Finally, compile and install the graphical users interface
Run BornAgain GUI
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-After installation is complete, run BornAgain GUI from command line
+After installation is complete the new ``BornAgain`` executable will appear in ``<install_dir>/bin`` directory.
+Make sure that BornAgain core libraries are in your PATH by running
.. code-block:: bash
source <install_dir>/bin/thisbornagain.sh
+
+and launch GUI
+
+
+.. code-block:: bash
+
<install_dir>/bin/BornAgain
.. seealso::
- :ref:`building_gui_label`
+ :ref:`using_gui_label`
+ :ref:`troubleshooting_label`
diff --git a/Doc/Sphinx/documentation/installation/installation_unix_short.rst b/Doc/Sphinx/documentation/installation/installation_unix_short.rst
index c11168e48c4a2c6f0618629b2e85337315900880..f2aaa8743a08010e0dde9ed3ef9e003b0ae27127 100644
--- a/Doc/Sphinx/documentation/installation/installation_unix_short.rst
+++ b/Doc/Sphinx/documentation/installation/installation_unix_short.rst
@@ -1,6 +1,8 @@
Installation instruction (short version)
-----------------------
+This page shortly explains how to build and install BornAgain framework from source on Unix platforms.
+
Install the third party software
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -44,3 +46,10 @@ Build and install the framework
.. code-block:: bash
$ cmake -DBORNAGAIN_GUI=ON -DCMAKE_INSTALL_PREFIX=<install_dir> <source_dir>
+
+.. seealso::
+
+ :ref:`detailed_installation_instruction_label`
+
+
+
\ No newline at end of file
diff --git a/Doc/Sphinx/documentation/troubleshooting/troubleshooting.rst b/Doc/Sphinx/documentation/troubleshooting/troubleshooting.rst
new file mode 100644
index 0000000000000000000000000000000000000000..c7fa6802edfe3411cfc450aecd5f96d9459b66b5
--- /dev/null
+++ b/Doc/Sphinx/documentation/troubleshooting/troubleshooting.rst
@@ -0,0 +1,26 @@
+.. _troubleshooting_label:
+
+Troubleshooting
+==========================
+
+
+BornAgain was successfully tested on a variety of Windows, MacOS and Unix platforms.
+Nevertheless, problems can still occur.
+
+We welcome feedback and bug reports related to the
+installation and use of BornAgain framework via
+
+* bornagain.project@gmail.com
+
+* `BornAgain Bug and Issue Tracker <http://apps.jcns.fz-juelich.de/redmine/projects/bornagain/issues>`_
+
+
+Please send us e-mail or fill in bug report providing all relevant information which will help us to quickly spot the problem.
+
+
+Please refer to the following sections which might help to identify the source of the problem
+
+.. toctree::
+ :maxdepth: 1
+
+ troubleshooting_installation_unix.rst
diff --git a/Doc/Sphinx/documentation/troubleshooting/troubleshooting_installation_unix.rst b/Doc/Sphinx/documentation/troubleshooting/troubleshooting_installation_unix.rst
new file mode 100644
index 0000000000000000000000000000000000000000..5384ba1f825070d6245e23706169206b55f7fac5
--- /dev/null
+++ b/Doc/Sphinx/documentation/troubleshooting/troubleshooting_installation_unix.rst
@@ -0,0 +1,45 @@
+
+
+Installation problems on Unix platforms
+------------------------------------------
+
+.. contents::
+ :depth: 1
+ :local:
+ :backlinks: none
+
+
+
+CMake configuration fails
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CMake might fail with the error message::
+
+ Configuring incomplete, errors occurred!
+
+or similar if some of the third party libraries are not installed on the system, or cmake is not able to find them.
+Please send us the log file ``my_cmake.log`` generated by running the following command in the empty ``<build_dir>``
+
+.. code-block:: bash
+
+ cmake -DCMAKE_INSTALL_PREFIX=<install_dir> <source_dir> >& my_cmake.log
+
+
+
+
+
+Compilation fails
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the case of a complex system setup, with libraries of different versions
+scattered across multiple places ``cmake`` might make an error in identifying correct paths to the libraries or include directories.
+This might lead at some point to the compilation failure.
+This might happen, for example, during compilation of BornAgain graphical user interface if the system has both Qt4 and Qt5 libraries installed.
+Please send us the build log by running following make command
+
+.. code-block:: bash
+
+ make VERBOSE=1 >& my_build.log
+
+
+
diff --git a/Doc/Sphinx/documentation/working_with_bornagain/using_gui.rst b/Doc/Sphinx/documentation/working_with_bornagain/using_gui.rst
index 1c1b7df5d42f4e402f26881e639e25ed11f59dea..3c89b9435ac9438fb5bce3d0e796a9154a953f04 100644
--- a/Doc/Sphinx/documentation/working_with_bornagain/using_gui.rst
+++ b/Doc/Sphinx/documentation/working_with_bornagain/using_gui.rst
@@ -228,7 +228,7 @@ reflecting the influence of this given parameter on the simulation results.
The jobs in Jobs View are completely isolated from the rest of the program. Any adjustments of sample parameters in Sample View or
instrument parameters in Instrument View
- won't have any influence on jobs already existing/running in Jobs View. Similarly, any parameter adjustments made in the parameter tree (3)
+ won't have any influence on jobs already completed or still running in Jobs View. Similarly, any parameter adjustments made in the parameter tree (3)
will not be propagated back into Sample or Instrument Views.