diff --git a/doc/cluster/index.rst b/doc/cluster/index.rst
index 3edf295dfb..544ca5e0f8 100644
--- a/doc/cluster/index.rst
+++ b/doc/cluster/index.rst
@@ -13,7 +13,7 @@ processes examining packets and doing correlation activities but acting as
 a singular, cohesive entity.  This document describes the Bro cluster
 architecture.  For information on how to configure a Bro cluster,
 see the documentation for
-`BroControl <http://bro.org/sphinx/components/broctl/README.html>`_.
+:doc:`BroControl <../components/broctl/README>`.
 
 Architecture
 ---------------
diff --git a/doc/install/guidelines.rst b/doc/install/guidelines.rst
index a5526a706e..af33b8fee1 100644
--- a/doc/install/guidelines.rst
+++ b/doc/install/guidelines.rst
@@ -1,16 +1,21 @@
 
 .. _upgrade-guidelines:
 
-==================
-General Guidelines
-==================
+==============
+How to Upgrade
+==============
 
 If you're doing an upgrade install (rather than a fresh install),
 there's two suggested approaches: either install Bro using the same
 installation prefix directory as before, or pick a new prefix and copy
-local customizations over. In the following we summarize general
-guidelines for upgrading, see the :ref:`release-notes` for
-version-specific information.
+local customizations over.  Regardless of which approach you choose,
+if you are using BroControl, then after upgrading Bro you will need to
+run "broctl check" (to verify that your new configuration is OK)
+and "broctl install" to complete the upgrade process.
+
+In the following we summarize general guidelines for upgrading, see
+the :ref:`release-notes` for version-specific information.
+
 
 Reusing Previous Install Prefix
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/install/install.rst b/doc/install/install.rst
index 7400d640fe..7a55f519a3 100644
--- a/doc/install/install.rst
+++ b/doc/install/install.rst
@@ -80,7 +80,7 @@ that ``bash`` and ``python`` are in your ``PATH``):
   Distributions of these dependencies can likely be obtained from your
   preferred Mac OS X package management system (e.g. MacPorts_, Fink_,
   or Homebrew_).  Specifically for MacPorts, the ``cmake``, ``swig``,
-  ``swig-python`` and packages provide the required dependencies.
+  and ``swig-python`` packages provide the required dependencies.
 
 
 Optional Dependencies
diff --git a/doc/quickstart/index.rst b/doc/quickstart/index.rst
index dc67e9839c..a61d0cc71d 100644
--- a/doc/quickstart/index.rst
+++ b/doc/quickstart/index.rst
@@ -15,7 +15,7 @@ source code forms.  See :ref:`installing-bro` for instructions on how to
 install Bro. 
 
 In the examples below, ``$PREFIX`` is used to reference the Bro
-installation root directory, which by default is ``/usr/local/bro/`` if
+installation root directory, which by default is ``/usr/local/bro`` if
 you install from source. 
 
 Managing Bro with BroControl
@@ -25,8 +25,8 @@ BroControl is an interactive shell for easily operating/managing Bro
 installations on a single system or even across multiple systems in a
 traffic-monitoring cluster.  This section explains how to use BroControl
 to manage a stand-alone Bro installation.  For instructions on how to
-configure a Bro cluster, see the documentation for `BroControl
-<http://bro.org/sphinx/components/broctl/README.html>`_.
+configure a Bro cluster, see the documentation for :doc:`BroControl
+<../components/broctl/README>`.
 
 A Minimal Starting Configuration
 --------------------------------