Added complete Doc Conventions in Install Guide.

backport: havana

Change-Id: Icd74a1a4db8ec477e48d49475c405d3b09e52c1c
Partial-Bug: #1121866

doc/install-guide/ch_swift.xml

@@ -3,9 +3,9 @@
          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 Object Storage</title>
+  <title>Add the Object Storage service</title>
 
-       <para>The OpenStack Object Storage services work together to provide object storage and retrieval through a REST API. For this example architecture, it's assumed you have the Identity Service (keystone) installed already.</para>
+       <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" />
        <xi:include
           href="object-storage/section_object-storage-sys-requirements.xml"/>

doc/install-guide/object-storage/section_object-storage-install-config-proxy-node.xml

@@ -10,8 +10,8 @@
         enable account management by configuring it in the
             <filename>proxy-server.conf</filename> file.</para>
     <note>
-        <para>Swift processes run under a separate user and group, set
-            by configuration options, and referred to as <phrase
+        <para>The Object Storage processes run under a separate user
+            and group, set by configuration options, and referred to as <phrase
                 os="ubuntu;debian;rhel;centos;fedora"
                 >swift:swift</phrase><phrase os="opensuse;sles"
                 >openstack-swift:openstack-swift</phrase>. The default

doc/install-guide/section_ceilometer-install.xml

@@ -3,9 +3,9 @@
   xmlns="http://docbook.org/ns/docbook"
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
-  <title>Install the Telemetry Service</title>
+  <title>Install the Telemetry service</title>
   <procedure>
-    <para>The OpenStack Telemetry  Service is an API service that
+    <para>OpenStack Telemetry is an API service that
       provides a collector and a range of disparate agents. Before
       you can install these agents on nodes such as the compute
       node, you must use this procedure to install the core

doc/install-guide/section_ceilometer-nova.xml

@@ -6,20 +6,21 @@
   <?dbhtml-stop-chunking?>
   <title>Install the Compute agent for the Telemetry service</title>
   <procedure>
-    <para>The Telemetry service consists of an API service, collector
-      and a range of disparate agents. This procedure details the
-      installation of the agent that runs on compute nodes.</para>
+    <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
+      nodes.</para>
     <step>
-      <para>Install the Telemetry service on the compute node:</para>
+      <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>
       <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-ceilometer-compute</userinput></screen>
       <screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install openstack-ceilometer-agent-compute</userinput></screen>
     </step>
     <step>
-      <para os="fedora;rhel;centos;opensuse;sles">Set the following options in the
-          <filename>/etc/nova/nova.conf</filename> file:</para>
-      <screen os="fedora;rhel;centos;opensuse;sles">
-<prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT instance_usage_audit True</userinput>
+      <para os="fedora;rhel;centos;opensuse;sles">Set the following
+        options in the <filename>/etc/nova/nova.conf</filename>
+        file:</para>
+      <screen os="fedora;rhel;centos;opensuse;sles"><prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT instance_usage_audit True</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT instance_usage_audit_period hour</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT notify_on_state_change vm_and_task_state</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT notification_driver nova.openstack.common.notifier.rpc_notifier</userinput>
@@ -53,13 +54,13 @@ notification_driver=ceilometer.compute.nova_notifier</programlisting>
 metering_secret = ADMIN_TOKEN
 ...</programlisting>
     </step>
-
     <step os="ubuntu;debian">
       <para>Restart the service with its new settings:</para>
       <screen><prompt>#</prompt> <userinput>service ceilometer-agent-compute restart</userinput></screen>
     </step>
     <step os="rhel;fedora;centos;opensuse;sles">
-      <para>Start the service and configure it to start when the system boots:</para>
+      <para>Start the service and configure it to start when the
+        system boots:</para>
       <screen os="opensuse;sles"><prompt>#</prompt> <userinput>service openstack-ceilometer-agent-compute start</userinput>
 <prompt>#</prompt> <userinput>chkconfig openstack-ceilometer-agent-compute on</userinput></screen>
       <screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>service openstack-ceilometer-compute start</userinput>

doc/install-guide/section_cinder-node.xml

@@ -41,15 +41,15 @@
         scanning devices used by virtual machines.</para>
       <note>
         <para>You must add required physical volumes for LVM on the
-          Cinder host. Run the <command>pvdisplay</command> command to
-          get a list or required volumes.</para>
+          Block Storage host. Run the <command>pvdisplay</command>
+          command to get a list or required volumes.</para>
       </note>
       <para>Each item in the filter array starts with either an
-          "<literal>a</literal>" for accept, or an
-          "<literal>r</literal>" for reject. Physical volumes that are
-        needed on the Cinder host begin with "<literal>a</literal>".
-        The array must end with "<literal>r/.*/</literal>" to reject
-        any device not listed.</para>
+          <literal>a</literal> for accept, or an
+          <literal>r</literal> for reject. The physical volumes that
+        are required on the Block Storage host have names that begin
+        with <literal>a</literal>. The array must end with
+        "<literal>r/.*/</literal>" to reject any device not listed.</para>
       <para>In this example, <literal>/dev/sda1</literal> is the
         volume where the volumes for the operating system for the node
         reside, while <literal>/dev/sdb</literal> is the volume
@@ -75,17 +75,17 @@ filter = [ "a/sda1/", "a/sdb/", "r/.*/"]
             ><literal>[keystone_authtoken]</literal> settings</link>,
         and <link linkend="debconf-rabbitqm">RabbitMQ
           credentials</link>. Make sure to enter the same details as
-        for your Block Storage Service controller node.</para>
+          your Block Storage Service controller node.</para>
       <para>Another screen prompts you for the <systemitem
           class="library">volume-group</systemitem> to use. The Debian
         package configuration script detects every active volume
         group, provided that the <systemitem class="library"
-          >lvm2</systemitem> package is installed before Cinder (this
-        should be the case if you configured the volume group first,
+          >lvm2</systemitem> package is installed before Block Storage
+        (this should be the case if you configured the volume group first,
         as this guide recommends), and tries to use the first one it
         sees. If you have only one active volume group on your Block
-        Storage Service node, you need not manually enter its name in
-        when you install the <systemitem class="service"
+        Storage Service node, you do not need to manually enter its
+        name in when you install the <systemitem class="service"
           >cinder-volume</systemitem> package because it is detected
         automatically. If no <systemitem class="library"
           >volume-group</systemitem> is available when you install

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 Horizon</link>.</para>
+            >Deploying the Horizon dashboard</link>.</para>
     <procedure>
         <step>
             <para>Install the dashboard on the node that can contact

doc/install-guide/section_glance-install.xml

@@ -5,8 +5,8 @@
   xmlns:svg="http://www.w3.org/2000/svg"
   xmlns:html="http://www.w3.org/1999/xhtml" version="5.0">
   <title>Install the Image Service</title>
-  <para>The Image Service acts as a registry for virtual disk images.
-    Users can add new images or take a snapshot of an image from an
+  <para>The OpenStack Image Service acts as a registry for virtual disk
+    images. Users can add new images or take a snapshot of an image from an
     existing server for immediate storage. Use snapshots for back up
     and as templates to launch new servers. You can store registered
     images in Object Storage or in other locations. For example, you

doc/install-guide/section_heat-install.xml

@@ -5,7 +5,7 @@
   <title>Install the Orchestration service</title>
   <procedure os="debian">
     <step>
-      <para>Install the Orchestration service on the controller
+      <para>Install the OpenStack Orchestration service on the controller
         node:</para>
       <screen os="debian"><prompt>#</prompt> <userinput>apt-get install heat-api heat-api-cfn heat-engine</userinput></screen>
     </step>
@@ -21,7 +21,7 @@
   </procedure>
   <procedure>
     <step>
-      <para>Install the Orchestration service on the controller
+      <para>Install the OpenStack Orchestration service on the controller
         node:</para>
       <screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install heat-api heat-api-cfn heat-engine</userinput></screen>
       <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-heat-api openstack-heat-engine openstack-heat-api-cfn</userinput></screen>

doc/install-guide/section_heat-verify.xml

@@ -5,10 +5,9 @@
 
   <title>Verify the Orchestration service installation</title>
 
-  <para>To verify that the Orchestration service is installed and
-    configured correctly, first ensure you have your credentials set
-    up correctly in an <filename>openrc</filename> file. Then, source
-    it so your environment has the user name and password.</para>
+  <para>To verify that the Orchestration service is installed and configured
+    correctly, make sure that your credentials are set up correctly in the
+    <filename>openrc</filename> file. Source the file, as follows:</para>
 
   <screen><prompt>#</prompt> <userinput>source openrc</userinput></screen>
 

doc/install-guide/section_keystone-install.xml

@@ -6,8 +6,8 @@
   <title>Install the Identity Service</title>
   <procedure>
     <step>
-      <para>Install the Identity Service on the controller node,
-        together with python-keystoneclient (which is a
+      <para>Install the OpenStack Identity Service on the controller node,
+        together with <application>python-keystoneclient</application> (which is a
         dependency):</para>
       <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>apt-get install keystone</userinput></screen>
       <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-keystone python-keystoneclient</userinput></screen>
@@ -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 keystone and other openstack services
+# A "shared secret" between OpenStack Identity Service 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 keystone and other openstack services
+# A "shared secret" between OpenStack Identity Service and other OpenStack services
 admin_token = ADMIN_TOKEN
 ...</programlisting>
     </step>

doc/install-guide/section_keystone-services.xml

@@ -3,12 +3,19 @@
   xml:id="keystone-services"
   os="rhel;centos;fedora;opensuse;sles;ubuntu">
   <title>Define services and API endpoints</title>
-  <para>The Identity Service also tracks what OpenStack services are
-    installed and where to locate them on the network. For each
-    service on your OpenStack installation, you must call
-      <command>keystone service-create</command> to describe the
-    service and <command>keystone endpoint-create</command> to specify
-    the API endpoints associated with the service.</para>
+  <para>The Identity Service also tracks what OpenStack services are installed
+    and where to locate them on the network. Run these commands for each
+    service in your OpenStack installation:</para>
+  <itemizedlist>
+    <listitem>
+      <para><command>keystone service-create</command>. Describes the
+        service.</para>
+    </listitem>
+    <listitem>
+      <para><command>keystone endpoint-create</command>. Associates
+        API endpoints with the service.</para>
+    </listitem>
+  </itemizedlist>
   <para>For now, create a service for the Identity Service itself that
     uses normal authentication instead of the authorization token when
     you run the <command>keystone</command> command in the

doc/install-guide/section_keystone-users.xml

@@ -4,12 +4,12 @@
          xml:id="keystone-users" os="rhel;centos;fedora;opensuse;sles;ubuntu">
   <title>Define users, tenants, and roles</title>
 
-  <para>Once Keystone is installed and running, you set up users, tenants,
-  and roles to authenticate against. These are used to allow access to
+  <para>After you install the Identity Service, set up users,
+  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 username and password to authenticate
-  with the Identity service. At this point, however, we have not created
+  <para>Typically, you would use a user name and password to authenticate
+  with the Identity Service. At this point, however, we have not created
   any users, so we have to use the authorization token created in the
   previous section. You can pass this with the <option>--os-token</option>
   option to the <command>keystone</command> command or set the

doc/install-guide/section_neutron-per-tenant-routers-with-private-networks.xml

@@ -4,9 +4,9 @@
     xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
     xml:id="section_networking-routers-with-private-networks">
     <title>Per-tenant routers with private networks</title>
-    <para>This section describes how to install the Networking service
-        and its components for a per-tenant routers with private
-        networks use case.</para>
+    <para>This section describes how to install the OpenStack Networking
+        service and its components for a use case that has per-tenant
+        routers with private networks.</para>
     <informalfigure>
         <mediaobject>
             <imageobject>

doc/install-guide/section_nova-network.xml

@@ -2,12 +2,11 @@
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
   xml:id="nova-network">
-  <title>Enable networking</title>
-  <para>Configuring networking can be a bewildering experience. The
-    following example shows the simplest production-ready
-    configuration that is available: the legacy networking in
-    OpenStack Compute, with a flat network, that takes care of
-    DHCP.</para>
+  <title>Enable Networking</title>
+  <para>The example in this section shows how to set up OpenStack
+   Compute networking to use a flat network and DHCP. This set up
+   is the simplest production-ready configuration that
+   is available.</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