Added link to Chef admins edit, admonition section.

Author: mboersma

docs/operations/provision-controller.rst

@@ -14,8 +14,8 @@ Automatic Provisioning
 The community maintains shell scripts that automate the provisioning
 of Deis controllers on different cloud providers.
 In addition to launching the controller itself, these scripts also
-use optimized base images, 
-generate SSH keys, firewall configs and other cloud infrastructure 
+use optimized base images,
+generate SSH keys, firewall configs and other cloud infrastructure
 per Deis best practices.
 
 You can find instructions on automatic provisioning for:
@@ -29,16 +29,16 @@ Please note that even with automatic provisioning, you will still have to
 
 Manual Provisioning
 -------------------
-If you want your controller on bare metal, a different cloud provider, 
-or would just rather provision things manually --no problem!  
+If you want your controller on bare metal, a different cloud provider,
+or would just rather provision things manually --no problem!
 Just remember with manual provisioning, you are in charge of:
 
  * Ensuring system requirements are met
  * SSH key generation and distribution
  * Network configuration
 
 .. important:: System Requirements
-   Most controllers require at least 2GB of system memory and 100GB of storage  
+   Most controllers require at least 2GB of system memory and 100GB of storage
 
 The general process for manual provisioning involves:
 
@@ -76,40 +76,46 @@ you must add "deis-controller" to the "admins" group on the Chef Server.
 
 Hosted Chef
 ~~~~~~~~~~~
-Users using Hosted Chef can perform these `steps` to add deis-controller to admin group.
+For Hosted Chef, visit the `OpsCode management interface`_ to add
+"deis-controller" to the "admins" group. These `steps`_ describe specifically
+how to add users to groups in the management interface.
 
 Open Source Chef
 ~~~~~~~~~~~~~~~~
 
-For opensource chef one can use knife cli tool. First, set the EDITOR environment variable to your favourite text editor.
+For Open Source Chef, use the knife cli tool. First, set the EDITOR environment
+variable to your favourite text editor:
 
 ``$ export EDITOR=vim``
 
-Now issue the command to edit ``deis-controller`` user.
+Now issue the command to edit the "deis-controller" user.
 
 ``$ knife client edit deis-controller``
 
 and update the 'admin' key to 'true'. The updated content should look similar to this.
 
-.. code-block:: console
+.. code-block:: json
 
-    {
+  {
     "name": "deis-controller",
-    "public_key": "-----BEGIN PUBLIC KEY-----\nMaaBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwzKA3YNTw0qD8hcPiJpT\naYSpJI0sQF4u6/WpE4HAlGRHpjpoG/QwtuA4sosW+ebNXDbxKhDoQxsHnz97jDuZ\n4nvnTdaJRGygXABEkuUG68cV7asdGzn76bRT3GNa4LD+ekqJON7nCA/K8V3AZ1P4\nWfnPc/RfmK3InQC92w1xsX2hpZ/qzeL3Y+jxaJ7SnGgm9Q5O7PnDObNW4exzo6936\nkZFCdmQIdVfy4sGASc8ep6NW8ZHuej8vcCdFKJut9QV3S8kDl1XF2sG2DV4qMbC/\nalFRnZUy0TckSgm3fiqfi89u2bbSlfzrTHv2NU9xaYDv7QQpFoZ62PKG9SdJ9R5G\nUwIDAQAB\n-----END PUBLIC KEY-----\n",
+    "public_key": "-----BEGIN PUBLIC KEY-----\nMaa...QAB\n-----END PUBLIC KEY-----\n",
     "admin": true,
     "json_class": "Chef::ApiClient",
     "chef_type": "client"
-    }
+  }
 
-Save and close the file. The user is now in admin group.
+Save and close the file. The "deis-controller" user is now in the "admins" group.
 
-If you skip this step, you will receive errors when scaling down nodes as the 
-controller will not have permissions to delete "client" and "node" records from the Chef Server.
+.. important::
+   If you skip adding "deis-controller" to the Chef "admins" group, you will
+   receive errors when scaling down nodes, as the controller will not have
+   permission to delete "client" and "node" records from the Chef Server.
 
 .. _`EC2`: https://github.com/opdemand/deis/tree/master/contrib/ec2#readme
 .. _`Rackspace`: https://github.com/opdemand/deis/tree/master/contrib/rackspace#readme
 .. _`Digital Ocean`: https://github.com/opdemand/deis/tree/master/contrib/digitalocean#readme
 .. _`add the controller to the admins group`: #add-controller-to-admins-group
 .. _`knife`: http://docs.opscode.com/knife.html
+.. _`OpsCode management interface`: https://manage.opscode.com/groups/admins/edit
 .. _`steps`: http://docs.opscode.com/manage_server_hosted_groups.html#add-user-to-group