diff --git a/packages/autoupdate/autoupdate_client.js b/packages/autoupdate/autoupdate_client.js
index f079689e60..d81ac91d30 100644
--- a/packages/autoupdate/autoupdate_client.js
+++ b/packages/autoupdate/autoupdate_client.js
@@ -1,5 +1,33 @@
+// Subscribe to the `meteor_autoupdate_clientVersions` collection,
+// which contains the set of acceptable client versions.
+//
+// A "hard code push" occurs when the current client version is not in
+// the set of acceptable client versions (or the server updates the
+// collection, and the current client version is no longer in the
+// set).
+//
+// When the `reload` package is loaded, a hard code push causes
+// the browser to reload, so that it will load the latest client
+// version from the server.
+//
+// A "soft code push" represents the situation when the current client
+// version is in the set of acceptable versions, but there is a newer
+// version available on the server.
+//
+// `AutoUpdate.newClientAvailable` is a reactive data source which
+// becomes `true` if there is a new version of the client is available on
+// the server.
+//
+// This package doesn't implement a soft code reload process itself,
+// but `newClientAvailable` could be used for example to display a
+// "click to reload" link to the user.
+
+// The client version of the client code currently running in the
+// browser.
 var autoUpdateVersion = __meteor_runtime_config__.autoUpdateVersion;
 
+
+// The collection of acceptable client versions.
 var ClientVersions = new Meteor.Collection("meteor_autoupdate_clientVersions");
 
 
diff --git a/packages/autoupdate/autoupdate_server.js b/packages/autoupdate/autoupdate_server.js
index 8f2ccfa0dc..2359cf28cb 100644
--- a/packages/autoupdate/autoupdate_server.js
+++ b/packages/autoupdate/autoupdate_server.js
@@ -1,8 +1,41 @@
+// Publish the current client version to the client.  When a client
+// sees the subscription change and that there is a new version of the
+// client available on the server, it can reload.
+//
+// By default the current client version is identified by a hash of
+// the client resources seen by the browser (the HTML, CSS, code, and
+// static files in the `public` directory).
+//
+// If the environment variable `AUTOUPDATE_VERSION` is set it will be
+// used as the client id instead.  You can use this to control when
+// the client reloads.  For example, if you want to only force a
+// reload on major changes, you can use a custom AUTOUPDATE_VERSION
+// which you only change when something worth pushing to clients
+// immediately happens.
+//
+// The server publishes a `meteor_autoupdate_clientVersions`
+// collection.  The contract of this collection is that each document
+// in the collection represents an acceptable client version, with the
+// `_id` field of the document set to the client id.
+//
+// An "unacceptable" client version, for example, might be a version
+// of the client code which has a severe UI bug, or is incompatible
+// with the server.  An "acceptable" client version could be one that
+// is older than the latest client code available on the server but
+// still works.
+//
+// One of the published documents in the collection will have its
+// `current` field set to `true`.  This is the version of the client
+// code that the browser will receive from the server if it reloads.
+//
+// In this implementation only one such document is published, the
+// current client version.  Developers can easily experiment with
+// different versioning and updating models by forking this package.
+
 var crypto = Npm.require('crypto');
 
 AutoUpdate = {};
 
-
 // The client hash includes __meteor_runtime_config__, so wait until
 // all packages have loaded and have had a chance to populate the
 // runtime config before using the client hash as our default auto
@@ -13,6 +46,7 @@ AutoUpdate.autoUpdateVersion = null;
 Meteor.startup(function () {
   AutoUpdate.autoUpdateVersion =
     process.env.AUTOUPDATE_VERSION ||
+    // also accept SERVER_ID for backwards compatibility.
     process.env.SERVER_ID ||
     WebApp.clientHash;