Bug 1151803 - Docs: Clarify the UI build/dist explanation & steps

Explains the reasoning behind the dist directory, and separates out the
"updating the dist directory" and "testing the dist directory" steps.

docs/deployment.rst

@@ -3,18 +3,12 @@ Deployment
 
 Serving the UI build from the dist directory
 --------------------------------------------
-This step required prior to deployment concatenates and minifies the js and css and moves all required assets to a directory in the project root called ``dist``. To do this:
 
-* Install the Grunt wrapper globally by running as root ``npm install -g grunt-cli``
-* Install local dependencies by running as root ``npm install`` from the project root
-* Then run the following command:
+During local development the UI is served in its original, unprocessed form. In
+production, a minified/built version of the UI (generated using grunt) is used instead.
 
-.. code-block:: bash
-
-    grunt build
-
-
-Then in ``Vagrantfile`` change ``serve_minified_ui`` to true:
+To serve the built version of the UI locally, in ``Vagrantfile`` change
+``serve_minified_ui`` to true:
 
 .. code-block:: ruby
 
@@ -23,3 +17,16 @@ Then in ``Vagrantfile`` change ``serve_minified_ui`` to true:
   }
 
 You will need to run ``vagrant provision`` to pick up those changes, if the Vagrant environment was already created.
+
+
+Updating the UI build prior to deployment
+-----------------------------------------
+
+Building the UI requires Node.js which is not installed on production, so the
+build output has to be checked into the repo. As such, prior to deployment, this
+must be updated manually. To do this:
+
+* Install the Grunt wrapper globally by running as root ``npm install -g grunt-cli``
+* Install local dependencies by running as root ``npm install`` from the project root
+* Run ``grunt build`` to refresh the contents of the ``dist`` directory.
+* Commit the result to the repo with a commit message similar to ``update grunt build``.