UG edits: sdk chapter and app_support appx

- Wanted to remove the Documentation Feedback section from app_support
- The same information is already included in the Documentation first section.
- But it looks like something else refers to it, so it's back in.
- Patch Set 3: fixed sdk_neutron and app_support

Change-Id: Ibb19265e1ee79300dc02eeab35da45e64eee1a48

doc/common/app_support.xml

@@ -229,33 +229,30 @@
     </section>
     <section xml:id="support-wiki">
         <title>The OpenStack wiki</title>
-        <para>The <link xlink:href="http://wiki.openstack.org/"
+        <para>The <link xlink:href="http://wiki.openstack.org/">OpenStack
-                >OpenStack wiki</link> contains a broad range of
+                wiki</link> contains a broad range of topics but some of the
-            topics but some of the information can be difficult to
+            information can be difficult to find or is a few pages deep.
-            find or is a few pages deep. Fortunately, the wiki search
+            Fortunately, the wiki search feature enables you to search by title
-            feature enables you to search by title or content. If you
+            or content. If you search for specific information, such as about
-            search for specific information, such as about networking
+            networking or nova, you can find a large amount of relevant
-            or nova, you can find lots of relevant material. More is
+            material. More is being added all the time, so be sure to check back
-            being added all the time, so be sure to check back often.
+            often. You can find the search box in the upper-right corner of any
-            You can find the search box in the upper right corner of
+            OpenStack wiki page.</para>
-            any OpenStack wiki page.</para>
     </section>
     <section xml:id="support-bugs-area">
         <title>The Launchpad Bugs area</title>
-        <para>The OpenStack community values your set up and testing
+        <para>The OpenStack community values your set up and testing efforts and
-            efforts and wants your feedback. To log a bug, you must
+            wants your feedback. To log a bug, you must sign up for a Launchpad
-            sign up for a Launchpad account at <link
+            account at <link xlink:href="https://launchpad.net/+login"
-                xlink:href="https://launchpad.net/+login"
+                >https://launchpad.net/+login</link>. You can view existing bugs
-                >https://launchpad.net/+login</link>. You can view
+            and report bugs in the Launchpad Bugs area. Use the search feature
-            existing bugs and report bugs in the Launchpad Bugs area.
+            to determine whether the bug has already been reported or already
-            Use the search feature to determine whether the bug has
+            been fixed. If it still seems like your bug is unreported, fill out
-            already been reported or even better, already fixed. If it
+            a bug report.</para>
-            still seems like your bug is unreported, fill out a bug
-            report.</para>
         <para>Some tips:</para>
         <itemizedlist>
             <listitem>
-                <para>Give a clear, concise summary!</para>
+                <para>Give a clear, concise summary.</para>
             </listitem>
             <listitem>
                 <para>Provide as much detail as possible in the
@@ -271,11 +268,12 @@
                         bc79c3ecc55929bac585d04a03475b72e06a3208</literal>.</para>
             </listitem>
             <listitem>
-                <para>Any deployment specific information is helpful,
+                <para>Any deployment-specific information is helpful, such as
-                    such as Ubuntu 14.04 or multi-node install.</para>
+                    whether you are using Ubuntu 14.04 or are performing a
+                    multi-node installation.</para>
             </listitem>
         </itemizedlist>
-        <para>The Launchpad Bugs areas are available here:</para>
+        <para>The following Launchpad Bugs areas are available:</para>
         <itemizedlist>
             <!-- Core projects, sorted alphabetically -->
             <listitem>
@@ -368,41 +366,34 @@
     </section>
     <section xml:id="support-irc-channel">
         <title>The OpenStack IRC channel</title>
-        <para>The OpenStack community lives and breathes in the
+        <para>The OpenStack community lives in the #openstack IRC channel on the
-            #openstack IRC channel on the Freenode network. You can
+            Freenode network. You can hang out, ask questions, or get immediate
-            hang out, ask questions, or get immediate feedback for
+            feedback for urgent and pressing issues. To install an IRC client or
-            urgent and pressing issues. To install an IRC client or
             use a browser-based client, go to <link
                 xlink:href="http://webchat.freenode.net"
-                >http://webchat.freenode.net/</link>. You can also use
+                >http://webchat.freenode.net/</link>. You can also use Colloquy
-            Colloquy (Mac OS X, <link
+            (Mac OS X, <link xlink:href="http://colloquy.info/"
-                xlink:href="http://colloquy.info/"
                 >http://colloquy.info/</link>), mIRC (Windows, <link
-                xlink:href="http://www.mirc.com/"
+                xlink:href="http://www.mirc.com/">http://www.mirc.com/</link>),
-                >http://www.mirc.com/</link>), or XChat (Linux). When
+            or XChat (Linux). When you are in the IRC channel and want to share
-            you are in the IRC channel and want to share code or
+            code or command output, the generally accepted method is to use a
-            command output, the generally accepted method is to use a
             Paste Bin. The OpenStack project has one at <link
                 xlink:href="http://paste.openstack.org"
-                >http://paste.openstack.org</link>. Just paste your
+                >http://paste.openstack.org</link>. Just paste your longer
-            longer amounts of text or logs in the web form and you get
+            amounts of text or logs in the web form and you get a URL that you
-            a URL you can paste into the channel. The OpenStack IRC
+            can paste into the channel. The OpenStack IRC channel is
-            channel is: <literal>#openstack</literal> on
+                <literal>#openstack</literal> on
-                <literal>irc.freenode.net</literal>. You can find a
+                <literal>irc.freenode.net</literal>. You can find a list of all
-            list of all OpenStack-related IRC channels at <link
+            OpenStack IRC channels at <link
                 xlink:href="https://wiki.openstack.org/wiki/IRC"
                 >https://wiki.openstack.org/wiki/IRC</link>.</para>
     </section>
     <section xml:id="support-documentation-feedback">
         <title>Documentation feedback</title>
-
         <para>To provide feedback on documentation, join and use the
-                <email>openstack-docs@lists.openstack.org</email>
+            <email>openstack-docs@lists.openstack.org</email> mailing list at
-            mailing list at <link
+            <link xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs">OpenStack
-                xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs"
+                Documentation Mailing List</link>, or <link xlink:href="https://bugs.launchpad.net/openstack-manuals/+filebug">report a bug</link>.</para>
-                >OpenStack Documentation Mailing List</link>, or <link
-                xlink:href="https://bugs.launchpad.net/openstack-manuals/+filebug"
-                >report a bug</link>.</para>
     </section>
     <section xml:id="distro-support">
         <title>OpenStack distribution packages</title>

doc/user-guide/section_cli_nova_configure_instances.xml

@@ -23,9 +23,7 @@
     <para>You create at least one key pair for each project. You can use the key
         pair for multiple instances that belong to that project. If you generate
         a key pair with an external tool, you can import it into OpenStack.</para>
-    <para>If an image uses a static root password or a static key set &ndash;
+    <para>If an image uses a static root password or a static key set&mdash;neither is recommended&mdash;you must not provide a key pair when you launch the instance.</para>
-        neither is recommended &ndash; you must not provide a key pair when you
-        launch the instance.</para>
     <para>A <emphasis role="italic">security group</emphasis> is a named
         collection of network access rules that you use to limit the types of
         traffic that have access to instances. When you launch an instance, you

doc/user-guide/section_sdk_auth_nova.xml

@@ -26,8 +26,8 @@ nova = novaclient.client.Client("1.1", auth_url=env['OS_AUTH_URL'],
                                 project_id=env['OS_TENANT_NAME'],
                                 region_name=env['OS_REGION_NAME'])</programlisting>
   <para>If you authenticate against an endpoint that uses a custom
-    authentication back-end, you must load the authentication plug-in
+    authentication back end, you must load the authentication plug-in and pass
-    and pass it to the constructor.</para>
+    it to the constructor.</para>
   <para>The Rackspace public cloud is an OpenStack deployment that
     uses a custom authentication back end. To authenticate against
     this cloud, you must install the <link

doc/user-guide/section_sdk_authenticate.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="sdk_auth">
   <title>Authenticate</title>
-  <para>You must authenticate against an OpenStack endpoint before you
+  <para>When using the SDK, you must authenticate against an OpenStack
-    can use OpenStack services. Each project uses a slightly different
+    endpoint before you can use OpenStack services. Each project uses
-    syntax for authentication.</para>
+    a slightly different syntax for authentication.</para>
   <para>You must typically authenticate against a specific version of
     a service. For example, a client might need to authenticate
     against Identity v2.0.</para>

doc/user-guide/section_sdk_configure_instances.xml

@@ -4,6 +4,8 @@
     xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
     xml:id="sdk_configure_instances">
     <title>Configure access and security for instances</title>
+    <para>When working with images in the SDK, you will call
+            <literal>novaclient</literal> methods.</para>
     <?dbhtml stop-chunking?>
     <section xml:id="add_keypair_sdk">
         <title>Add a keypair</title>
@@ -25,11 +27,11 @@ ABaNPm1nRWm/ZDHnxCsFTcAl2LYOQXx3Cl2qKNY4r2di4G48GAkd\n7k5lDP2RgQatUM8npO0CD9PU
 mmrceYYK08/lQ7JKLmVkdzdQKt77+v1oBBuHiykLfI6h1m77NRDw9r8cV\nzczYeoALifpjTPMkKS8
 ECfDCuDn/vc9K1He8CRaJHf8AMLQLM3MN
 -----END RSA PRIVATE KEY-----</computeroutput></screen>
-    <para>You typically write the private key to a file to use it
+    <para>You typically write the private key to a file to use it later. The
-    later. The file must be readable and writeable by only the file owner,
+            file must be readable and writeable by only the file owner;
-    otherwise the ssh client will refuse to read the private key file. It
+            otherwise, the SSH client will refuse to read the private key file.
-    is safest to create the file with the appropriate permissions, as shown in
+            It is safest to create the file with the appropriate permissions, as
-    the following example:</para>
+            shown in the following example:</para>
     <programlisting language="python">import novaclient.v1_1.client as nvclient
 import os
 nova = nvclient.Client(...)

doc/user-guide/section_sdk_manage_images.xml

@@ -5,10 +5,12 @@
   xml:id="sdk_manage_images">
   <?dbhtml stop-chunking?>
   <title>Manage images</title>
+  <para>When working with images in the SDK, you will call both
+      <literal>glance</literal> and <literal>nova</literal> methods.</para>
   <section xml:id="sdk-glance-image-list">
     <title>List images</title>
-    <para>To list the available images, call the <methodname>
+    <para>To list the available images, call the
-        glanceclient.v2.images.Controller.list</methodname>
+        <methodname>glanceclient.v2.images.Controller.list</methodname>
       method:</para>
     <programlisting language="python">import glanceclient.v2.client as glclient
 glance = glclient.Client(...)

doc/user-guide/section_sdk_neutron.xml

@@ -40,7 +40,7 @@ export OS_AUTH_URL="http://<replaceable>IPADDRESS</replaceable>/v2.0"</programli
         <programlisting language="python">credentials = get_credentials()</programlisting>
     </section>
      <section xml:id="sdk_neutron_get_nova_credentials">
-        <title>Get nova credentials</title>
+        <title>Get Nova credentials</title>
         <para>Few examples in this section use the
                 <code>get_nova_credentials</code> method:</para>
         <programlisting language="python">def get_nova_credentials():