Install Guides: Edits based on Anne's comments

Revert and fix some changes as commented on in:
https://review.openstack.org/#/c/60493

Change-Id: Id6355a84bdfeed43a4d2b9657df8745cbc80c632
backport: havana

doc/install-guide/ch_swift.xml

@@ -3,7 +3,7 @@
          xmlns:xi="http://www.w3.org/2001/XInclude"
          xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
          xml:id="ch_swift">
-  <title>Add the Object Storage service</title>
+  <title>Add Object Storage</title>
 
        <para>The OpenStack Object Storage services work together to provide object storage and retrieval through a REST API. For this example architecture, you must have already installed the Identity Service, also known as Keystone.</para>
        <xi:include href="../common/section_getstart_object-storage.xml" />

doc/install-guide/section_ceilometer-nova.xml

@@ -8,8 +8,8 @@
   <procedure>
     <para>OpenStack Telemetry is an API service that provides a
       collector and a range of disparate agents. This procedure
-      details how to install the agent that runs on Compute
+      details how to install the agent that runs on the compute
-      nodes.</para>
+      node.</para>
     <step>
       <para>Install the Telemetry service on the Compute node:</para>
       <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>apt-get install ceilometer-agent-compute</userinput></screen>

doc/install-guide/section_dashboard-install.xml

@@ -22,7 +22,7 @@
     <para>For more information about how to deploy the dashboard, see
             <link
             xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html"
-            >Deploying the Horizon dashboard</link>.</para>
+            >deployment topics in the developer documentation</link>.</para>
     <procedure>
         <step>
             <para>Install the dashboard on the node that can contact

doc/install-guide/section_keystone-install.xml

@@ -94,7 +94,7 @@ IDENTIFIED BY '<replaceable>KEYSTONE_DBPASS</replaceable>';</userinput></screen>
         contains the password you have set using
           <package>debconf</package>:
         <programlisting language="ini">[DEFAULT]
-# A "shared secret" between OpenStack Identity Service and other OpenStack services
+# A "shared secret" between keystone and other openstack services
 admin_token = ADMIN_TOKEN
 ...</programlisting></para>
     </step>
@@ -179,7 +179,7 @@ admin_token = ADMIN_TOKEN
         the <literal>[DEFAULT]</literal> section, replacing
         ADMIN_TOKEN with the results of the command.</para>
       <programlisting os="ubuntu" language="ini">[DEFAULT]
-# A "shared secret" between OpenStack Identity Service and other OpenStack services
+# A "shared secret" between keystone and other openstack services
 admin_token = ADMIN_TOKEN
 ...</programlisting>
     </step>

doc/install-guide/section_keystone-users.xml

@@ -8,17 +8,18 @@
   tenants, and roles to authenticate against. These are used to allow access to
   services and endpoints, described in the next section.</para>
 
-  <para>Typically, you would use a user name and password to authenticate
+  <para>Typically, you would indicate a user and password to
-  with the Identity Service. At this point, however, we have not created
+    authenticate with the Identity Service. At this point, however, we
-  any users, so we have to use the authorization token created in the
+    have not created any users, so we have to use the authorization
-  previous section. You can pass this with the <option>--os-token</option>
+    token created in the previous section. You can pass this with the
-  option to the <command>keystone</command> command or set the
+      <option>--os-token</option> option to the
-  <envar>OS_SERVICE_TOKEN</envar> environment variable. We'll set
+      <command>keystone</command> command or set the
-  <envar>OS_SERVICE_TOKEN</envar>, as well as
+      <envar>OS_SERVICE_TOKEN</envar> environment variable. We'll set
-  <envar>OS_SERVICE_ENDPOINT</envar> to specify where the Identity
+      <envar>OS_SERVICE_TOKEN</envar>, as well as
-  Service is running. Replace
+      <envar>OS_SERVICE_ENDPOINT</envar> to specify where the Identity
-  <userinput><replaceable>FCAF3E...</replaceable></userinput>
+    Service is running. Replace
-  with your authorization token.</para>
+        <userinput><replaceable>FCAF3E...</replaceable></userinput>
+    with your authorization token.</para>
 
   <screen><prompt>#</prompt> <userinput>export OS_SERVICE_TOKEN=<replaceable>FCAF3E...</replaceable></userinput>
 <prompt>#</prompt> <userinput>export OS_SERVICE_ENDPOINT=http://controller:35357/v2.0</userinput></screen>

doc/install-guide/section_nova-network.xml

@@ -3,10 +3,10 @@
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
   xml:id="nova-network">
   <title>Enable Networking</title>
-  <para>The example in this section shows how to set up OpenStack
+  <para>Configuring Networking can be a bewildering experience. The
-   Compute networking to use a flat network and DHCP. This set up
+    following example shows the simplest production-ready configuration
-   is the simplest production-ready configuration that
+    that is available: the legacy networking in OpenStack Compute, with
-   is available.</para>
+    a flat network, that takes care of DHCP.</para>
   <para>This set up uses multi-host functionality. Networking is
     configured to be highly available by distributing networking
     functionality across multiple hosts. As a result, no single