diff --git a/Examples/python/fitting/README b/Examples/python/fitting/README
index a384ae49eea281041103bfb6a05e8f79c60246f7..b8de75de7183b47f8620b492e6b0cfa807bbae5a 100644
--- a/Examples/python/fitting/README
+++ b/Examples/python/fitting/README
@@ -24,16 +24,16 @@ used for fitting.
 --- ex04_FitScaleAndShift ---
     FitScaleAndShift.py - in this example we are trying to fit the data representing cylinders without interference
     on top of substrate. Real data contains some "unknown" background and scale factors.
-    In four parameters fit we are looking for cylinder's height and radius and for background and scale factors.
+    In four parameters fit we are looking for cylinder's height, radius and for background and scale factors.
 
 --- ex05_FitWithMasks ---
     FitWithMasks.py - two parameter fit of cylinders without interference.
-    Real data contains rectangular masks to simulate and fit only the area outside the masks.
+    Real data contains various masks to simulate and fit only the area outside the masks.
 
 --- ex06_FitStrategies ---
     FitStrategyAdjustMinimizer.py - in this example we are trying to find cylinder's height and radius using chain
     of minimizers. During the first fit round Genetic minimizer will be used. It will roughly look for possible
-    global minimas. After it is done, the second Minuit2 minimizer will continue to find the precise location of local
+    minimas. After it is done, the second Minuit2 minimizer will continue to find the precise location of global
     minima.
 
 --- ex07_FitAlongSlices ---
@@ -42,7 +42,9 @@ used for fitting.
     This will make simulation and fitting to go along slices only.
 
 --- ex08_SimultaneousFitOfTwoDatasets ---
-    SimultaneousFitOfTwoDatasets.py - here we demonstrate how to fit two datasets simultaneously.
+    SimultaneousFitOfTwoDatasets.py - simultaneous fit of two datasets.
+    It can be useful when, for example, we have same sample measured for two different incident angles and we
+    want to find unknown sample parameter using all data available.
 
 --- ex10_ImportUserData
     This directory contains examples for importing raw X,Y detector data into BornAgain's
diff --git a/Examples/python/fitting/ex01_SampleParametersIntro/SampleParametersIntro.py b/Examples/python/fitting/ex01_SampleParametersIntro/SampleParametersIntro.py
index 4fb2eb37743f7b3c48cc1b0b656eae13e9ddb58e..dde849c24d826431c0a2bd041eb129cd345e6cb0 100644
--- a/Examples/python/fitting/ex01_SampleParametersIntro/SampleParametersIntro.py
+++ b/Examples/python/fitting/ex01_SampleParametersIntro/SampleParametersIntro.py
@@ -14,7 +14,7 @@ from bornagain import *
 
 def get_sample():
     """
-    Build and return the sample representing cylinders and pyramids on top of
+    Build and return the sample representing cylinders and prisms on top of
     substrate without interference. Sample is made for fixed set of parameters.
     """
     # defining materials
diff --git a/Examples/python/fitting/ex02_FitCylindersAndPrisms/FitCylindersPrisms_detailed.py b/Examples/python/fitting/ex02_FitCylindersAndPrisms/FitCylindersPrisms_detailed.py
index 5df855c435ccfc665dff6e9888db7b80df8c9387..cd9c39cd7c55e67ac8f1e31867187b4726a43d8a 100644
--- a/Examples/python/fitting/ex02_FitCylindersAndPrisms/FitCylindersPrisms_detailed.py
+++ b/Examples/python/fitting/ex02_FitCylindersAndPrisms/FitCylindersPrisms_detailed.py
@@ -47,7 +47,7 @@ def get_sample(cylinder_height=1.0*nanometer, cylinder_radius=1.0*nanometer,
 def create_real_data():
     """
     Generating "real" data by adding noise to the simulated data.
-    This function has been used once to generate refdata_fitcylinderprisms.int
+    This function has been used once to generate refdata_fitcylinderprisms.int located in same directory
     """
     # creating sample with set of parameters we will later try to find during the fit
     sample = get_sample(5.0*nanometer, 5.0*nanometer, 5.0*nanometer, 5.0*nanometer)
@@ -66,7 +66,10 @@ def create_real_data():
         if noisy_amplitude < 0.0:
             noisy_amplitude = 0.0
         real_data.setBinContent(i, noisy_amplitude)
-    IntensityDataIOFactory.writeIntensityData(real_data, 'refdata_fitcylinderprisms.int')
+
+    # ucomment line to save generated data on disk
+    #IntensityDataIOFactory.writeIntensityData(real_data, 'refdata_fitcylinderprisms.int')
+    return real_data
 
 
 def get_simulation():
@@ -92,7 +95,6 @@ class DrawObserver(IFitObserver):
         self.fig.canvas.draw()
         plt.ion()
 
-
     def plot(self, data, title, nplot, min=1, max=1e6):
         plt.subplot(2, 2, nplot)
         plt.subplots_adjust(wspace=0.2, hspace=0.2)
@@ -112,7 +114,7 @@ class DrawObserver(IFitObserver):
         plt.subplot(2, 2, 4)
         plt.title('Parameters')
         plt.axis('off')
-        plt.text(0.01, 0.85, "Iteration  " + '{:d}     {:s}'.
+        plt.text(0.01, 0.85, "Iterations  " + '{:d}     {:s}'.
                  format(fit_suite.getNumberOfIterations(), fit_suite.getMinimizer().getMinimizerName()))
         plt.text(0.01, 0.75, "Chi2       " + '{:8.4f}'.format(fit_suite.getChi2()))
         fitpars = fit_suite.getFitParameters()
@@ -131,14 +133,11 @@ def run_fitting():
     main function to run fitting
     """
 
-    # uncomment to regenerate file with "real" data
-    # create_real_data()
-
     sample = get_sample()
     simulation = get_simulation()
     simulation.setSample(sample)
 
-    real_data = IntensityDataIOFactory.readIntensityData('refdata_fitcylinderprisms.int.gz')
+    real_data = create_real_data()
 
     fit_suite = FitSuite()
     fit_suite.addSimulationAndRealData(simulation, real_data)
diff --git a/Examples/python/fitting/ex04_FitScaleAndShift/FitScaleAndShift.py b/Examples/python/fitting/ex04_FitScaleAndShift/FitScaleAndShift.py
index 2f75e9af368a64c7915f88672b91b69b1194556a..2096bfc6525ec45263d562382f540cb18e485663 100644
--- a/Examples/python/fitting/ex04_FitScaleAndShift/FitScaleAndShift.py
+++ b/Examples/python/fitting/ex04_FitScaleAndShift/FitScaleAndShift.py
@@ -1,5 +1,5 @@
 """
-Fitting example: looking for background and scale factor.
+Fitting example: looking for background and scale factors.
 
 Real data contains some "unknown" background and scale factors.
 In the fit we are trying to find cylinder radius and height, scale and background factors.
diff --git a/Examples/python/fitting/ex05_FitWithMasks/FitWithMasks.py b/Examples/python/fitting/ex05_FitWithMasks/FitWithMasks.py
index ea590d13b49834521da990a2e013a0078a41c79d..b7c22013b296c89db1dbf4fe314979016e3312b5 100644
--- a/Examples/python/fitting/ex05_FitWithMasks/FitWithMasks.py
+++ b/Examples/python/fitting/ex05_FitWithMasks/FitWithMasks.py
@@ -83,24 +83,20 @@ def add_mask_to_simulation(simulation):
     # mask all detector (put mask=True to all detector channels)
     simulation.maskAll()
 
-    # # set mask to simulate pacman's head
-    # simulation.addMask(Ellipse(0.0*deg, 1.0*deg, 0.5*deg, 0.5*deg), False)
-    #
-    # # set mask for pacman's eye
-    # simulation.addMask(Ellipse(0.11*deg, 1.25*deg, 0.05*deg, 0.05*deg), True)
-    #
-    # # set mask for pacman's mouth
-    # points = [[0.0*deg, 1.0*deg], [0.5*deg, 1.2*deg], [0.5*deg, 0.8*deg], [0.0*deg, 1.0*deg]]
-    # simulation.addMask(Polygon(points), True)
-    #
-    # # giving pacman something to eat
-    # simulation.addMask(Rectangle(0.45*deg, 0.95*deg, 0.55*deg, 1.05*deg), False)
-    # simulation.addMask(Rectangle(0.61*deg, 0.95*deg, 0.71*deg, 1.05*deg), False)
-    # simulation.addMask(Rectangle(0.75*deg, 0.95*deg, 0.85*deg, 1.05*deg), False)
-
-    simulation.addMask(HorizontalLine(1.0*deg), False)
-    simulation.addMask(VerticalLine(0.0*deg), False)
+    # set mask to simulate pacman's head
+    simulation.addMask(Ellipse(0.0*deg, 1.0*deg, 0.5*deg, 0.5*deg), False)
 
+    # set mask for pacman's eye
+    simulation.addMask(Ellipse(0.11*deg, 1.25*deg, 0.05*deg, 0.05*deg), True)
+
+    # set mask for pacman's mouth
+    points = [[0.0*deg, 1.0*deg], [0.5*deg, 1.2*deg], [0.5*deg, 0.8*deg], [0.0*deg, 1.0*deg]]
+    simulation.addMask(Polygon(points), True)
+
+    # giving pacman something to eat
+    simulation.addMask(Rectangle(0.45*deg, 0.95*deg, 0.55*deg, 1.05*deg), False)
+    simulation.addMask(Rectangle(0.61*deg, 0.95*deg, 0.71*deg, 1.05*deg), False)
+    simulation.addMask(Rectangle(0.75*deg, 0.95*deg, 0.85*deg, 1.05*deg), False)
 
     # other mask's shapes are possible too
     # simulation.removeMasks()
diff --git a/Examples/python/fitting/ex06_FitStrategies/FitStrategyAdjustMinimizer.py b/Examples/python/fitting/ex06_FitStrategies/FitStrategyAdjustMinimizer.py
index e8efff4ec2a3238fbc6ab32e009315cd48f5509b..0fd55c0982a38d99734379bd0c8deeabd5aae895 100644
--- a/Examples/python/fitting/ex06_FitStrategies/FitStrategyAdjustMinimizer.py
+++ b/Examples/python/fitting/ex06_FitStrategies/FitStrategyAdjustMinimizer.py
@@ -2,8 +2,9 @@
 Two parameter fit of cylinders.
 In this example we are trying to find cylinder's height and radius using chain of minimizers.
 
-During the first fit round Genetic minimizer will be used. It will roughly look for possible global minimas.
-After it is done, the second Minuit2 minimizer will continue to find the precise location of local minima.
+During the first fit round Genetic minimizer will be used. It will roughly look for possible local minimas.
+After it is done, the second Minuit2 minimizer will continue to find the precise location of best minima
+found on previous step.
 """
 
 import numpy
diff --git a/Examples/python/fitting/ex08_SimultaneousFitOfTwoDatasets/SimultaneousFitOfTwoDatasets.py b/Examples/python/fitting/ex08_SimultaneousFitOfTwoDatasets/SimultaneousFitOfTwoDatasets.py
index 1b823bf937af8a81e5ff5d77b59a7db4f106a5aa..2414ac3e68474fcf9de68c31f7d6972bf39a10c8 100644
--- a/Examples/python/fitting/ex08_SimultaneousFitOfTwoDatasets/SimultaneousFitOfTwoDatasets.py
+++ b/Examples/python/fitting/ex08_SimultaneousFitOfTwoDatasets/SimultaneousFitOfTwoDatasets.py
@@ -1,7 +1,7 @@
 """
 Fitting example: demonstrates how to fit two datasets simultaneously.
 
-Suppose that we have same sample measured for two different incidence angles. We are going to fit both datasets
+Suppose that we have same sample measured for two different incident angles. We are going to fit both datasets
 simultaneously to find unknown sample parameters.
 
 To do this, we define one dataset ( a pair of real_data and simulation model) for the first incidence angle