diff --git a/docs/python/modelspec/programmatic/topology/geometry.rst b/docs/python/modelspec/programmatic/topology/geometry.rst
index edc855739d..9ff6a7b3f8 100755
--- a/docs/python/modelspec/programmatic/topology/geometry.rst
+++ b/docs/python/modelspec/programmatic/topology/geometry.rst
@@ -54,8 +54,13 @@ There are two ways to specify section geometry:
  
 Choose the stylized method if the notions of cable length and diameter 
 are authoritative and where 3-d shape is irrelevant. For plotting purposes, 
+e.g. using :class:`Shape` or :class:`PlotShape`,
 length and diameter will be used to generate 3-d info automatically for 
-a stylized straight cylinder. (see :func:`define_shape`) 
+a stylized straight cylinder. (see :func:`define_shape`) . This
+translation of length-diameter information into 3-d points, and then
+back again can make small changes to length and diameter since 3-d
+points are stored as 32bit floating point numbers which have about 7
+decimal digits of precision.
  
 Choose the 3-D method if the shape comes from 3-d reconstruction data 
 or if your 3-d visualization is paramount. This method makes the 3-d info 
@@ -854,11 +859,24 @@ Reading 3D Data from NEURON
         a logical connection point if the translation ruins the 
         visualization. 
          
+        pt3d information is stored as 32 bit floating point numbers. These
+        numbers have about 7 decimal digits of resolution. In contrast, most
+        other values in NEURON are double precision and have about 16 decimal
+        digits of resolution. Thus values of diam which do not happen to have
+        exact single precision representation, can change slightly in the
+        process of translating from diam to 3-d points and then back to diam.
+        Note that the latter transformation happens when an internal function
+        checks the :data:`diam_changed` variable and if non-zero, calls the internal
+        function, recalc_diam. This latter function can be called by several
+        functions such as :func:`finitialize`, segment.area(), and segment.ri()
+        See :func:`pt3dconst` for more about interpolation issues.
+
         Note: This may not work right when a branch is connected to 
         the interior of a parent section \ ``0 < x < 1``, 
         rather only when it is connected to the parent at 0 or 1. 
 
-         
+        When :class:`Shape` or :class:`PlotShape` instances are created
+        this function is called automatically.
 
 ----
 
diff --git a/docs/python/visualization/plotshapeclass.rst b/docs/python/visualization/plotshapeclass.rst
index dd1fd6200c..88380deedb 100755
--- a/docs/python/visualization/plotshapeclass.rst
+++ b/docs/python/visualization/plotshapeclass.rst
@@ -10,7 +10,7 @@ PlotShape
         Class for making a Shape window useful for coloring a shape 
         according to a variable value and creating time and space graphs 
         of a variable. The default variable is *v*. The first arg may be 
-        a SectionList. 
+        a SectionList.  This automatically calls :func:`define_shape`.
 
 ----
 
diff --git a/docs/python/visualization/shape.rst b/docs/python/visualization/shape.rst
index 6274e527c3..f791a6d97c 100755
--- a/docs/python/visualization/shape.rst
+++ b/docs/python/visualization/shape.rst
@@ -14,7 +14,7 @@ Shape
         If the first arg is a :class:`SectionList` (then a second arg of 0 will 
         prevent default mapping) then only the sections in the list are 
         drawn. Shape is redrawn automatically whenever length or diameter 
-        of a section changes. 
+        of a section changes. This automatically calls :func:`define_shape`.
         
         .. warning::