diff --git a/doc/compute_msd.txt b/doc/compute_msd.txt
index c95f5a8b6b..fc8327de5c 100644
--- a/doc/compute_msd.txt
+++ b/doc/compute_msd.txt
@@ -53,8 +53,23 @@ the center-of-mass of the group of atoms is subtracted out before the
 displacment of each atom is calculated.
 
 If the {average} option is set to {yes} then the reference position of 
-an atom is a running average of the atom position over all the calls
-to the msd calculation since the compute was invoked.
+an atom is based on the average position of that atom, 
+corrected for center-of-mass motion if requested.
+The average position
+is a running average over all previous calls to the compute, including the
+current call. So on the first call 
+it is current position, on the second call it is the arithmetic average of the 
+current position and the position on the first call, and so on.
+Note that when using this option, the precise value of the mean square
+displacement will depend on the number of times the compute is 
+called. So, for example, changing the frequency of thermo output may
+change the computed displacement. Also, the precise values will be 
+changed if a single simulation is broken up into two parts, using
+either multiple run commands or a restart file. It only makes
+sense to use this option if the atoms are not diffusing, so that
+their average positions relative to the center of mass of the system
+are stationary. The most common case is crystalline solids undergoing
+thermal motion.
 
 IMPORTANT NOTE: Initial coordinates are stored in "unwrapped" form, by
 using the image flags associated with each atom.  See the "dump