diff --git a/Analysis/Ostap/doc/release.notes b/Analysis/Ostap/doc/release.notes
index 205f824fc8b62beb05004925f56dfa9bd2133c0a..2c934cca8f7b593b5e809adf9c527a8c63e99fd7 100644
--- a/Analysis/Ostap/doc/release.notes
+++ b/Analysis/Ostap/doc/release.notes
@@ -8,6 +8,9 @@
 !  by                $Author$
 ! -----------------------------------------------------------------------------
 
+! 2017-01-27 - Vanya Belyaev
+ - impove documentation for pid_calib script 
+
 ! 2017-01-24 - Vanya Belyaev
  - Kisa.py, TreeDeco.py
    - improve tree/chain -> histogram projections
diff --git a/Analysis/Ostap/python/Ostap/pid_calib.py b/Analysis/Ostap/python/Ostap/pid_calib.py
index 5fc1ee990c957d53536b5588b4c49758ce8739e2..0cb26b30b78e80095230944a66c73b9ed1f6645e 100755
--- a/Analysis/Ostap/python/Ostap/pid_calib.py
+++ b/Analysis/Ostap/python/Ostap/pid_calib.py
@@ -11,18 +11,39 @@
 #  pid_calib.py Pi -s 20 -p MagUp -c 'Pi_hasRich==1' 
 #  @endocode
 #
+#  Typical usage with the proper environment:
+#  - one can use Analysis, DaVinci or Bender as ``main'' project
+#  - one needs to use Urania as ``runtime project''
+#  - Recent Urania requires access to LCHbDirac
+#
+#  Combine three projects into single working environment:
+#  @code
+#  lb-run LHCbDirac  bash -norc
+#  lb-rub --runtime-project Urania/v6r0  Bender/v30r1 pid_calib.py Pi -s 20 -p MagUp -c 'Pi_hasRich==1'
+#  @endcode
+# 
 #  @author Vanya BELYAEV Ivan.Belyaev@itep.ru
 #  @date   2014-05-10
 #  
-#                    $Revision$
-#  Last modification $Date$
-#  by                $Author$
 # =============================================================================
 """ An example of simple script to run PIDCalib machinery
 
-    pid_calib.py Pi -s 20 -p MagUp -c 'Pi_hasRich==1'
+> pid_calib.py Pi -s 20 -p MagUp -c 'Pi_hasRich==1'
+
+Use '-h' option to know more 
+
+Typical usage with the proper environment:
+
+- one can use Analysis, DaVinci or Bender as ``main'' project
+- one needs to use Urania as ``runtime project''
+- Recent Urania requires explicit access to LHCbDirac
+
+Combine three projects into single working environment:
+
+> lb-run LHCbDirac  bash -norc
+> lb-rub --runtime-project Urania/v6r0 Bender/v30r1 pid_calib.py Pi -s 20 -p MagUp -c 'Pi_hasRich==1'
+(here one combines LHCbDirac/latest Urania/v6r0 and Bender/v30r1)
 
-    Use '-h' option to know more 
 """
 # =============================================================================
 __version__ = "$Revision$"
@@ -62,8 +83,8 @@ def  PION ( particle         ,
     import ROOT
     from Ostap.PyRoUts import hID, h3_axes  
     
-    #
-    ## the heart of the whole game: 
+    # 
+    ## the heart of the whole game:   DEFINE PID CUTS! 
     # 
     accepted = 'Pi_V2ProbNNpi>0.1'  ## ACCEPTED sample 
     rejected = 'Pi_V2ProbNNpi<0.1'  ## REJECTED sample 
@@ -78,9 +99,10 @@ def  PION ( particle         ,
     vlst = ROOT.RooArgList ()
     vlst.add ( dataset.Pi_P    ) ## VARIABLE 
     vlst.add ( dataset.Pi_Eta  ) ## VARIABLE 
-    vlst.add ( dataset.nTracks ) ## VARIABLE 
+    vlst.add ( dataset.nTracks ) ## VARIABLE
+    
     #
-    ## binning
+    ## DEFINE PROPER BINNING FOR THE HISTOGRAMS 
     #
     ## binning in P 
     pbins    = [ 3.2  , 6  , 9  ,  15 , 20  , 30  , 40 , 50 , 60 , 80 , 100 , 120 , 150 ]
@@ -93,7 +115,7 @@ def  PION ( particle         ,
     tbins    = [0, 150 , 250 , 400 , 1000]
 
     #
-    ## book histograms
+    ## book 3D-histograms
     #
     ha       = h3_axes ( pbins , hbins , tbins , title = 'Accepted(%s)' % accepted ) 
     hr       = h3_axes ( pbins , hbins , tbins , title = 'Rejected(%s)' % rejected )
@@ -107,7 +129,7 @@ def  PION ( particle         ,
     #
     ## prepare the output
     #
-    if not plots : ## create outptu plots
+    if not plots : ## create output plots
         
         ha.SetName ( ha.GetTitle() )
         hr.SetName ( hr.GetTitle() )