Updated: About OpenStack Object Storage Document

One of the TODO entries was to provide a more comprehensive overview
of Object Storage/Swift than was already written. This is a first
attempt at making it better.

This patch also uncomments a line within the 'admin-guide-cloud' book
that doesn't reference the common 'about-object-storage' page like others
do. I've reverted this and tested thoroughly, not sure why this was there.

In addition, I updated a few other pages where they lacked certain
clarity. For example- the 'Getting Started' page provided only a very
basic overview of the components and without going into too much detail
I added further information. There were also a few English syntax changes
throughout some of the other pages.

Change-Id: I1952d9e1882fc962320304759110a2ccbc50de82
backport: havana

doc/admin-guide-cloud/ch_objectstorage.xml

@@ -5,14 +5,6 @@
     xml:id="ch_admin-openstack-object-storage">
     <?dbhtml stop-chunking?>
     <title>Object Storage</title>
-    <para>Object Storage is a scalable object storage system and not a
+    <xi:include href="../common/section_about-object-storage.xml"/>
-        file system in the traditional sense. You cannot mount this
-        system like traditional SAN or NAS volumes. Because Object
-        Storage requires a different way of thinking when it comes to
-        storage, take a few moments to review the key concepts in the
-        developer documentation at <link
-            xlink:href="http://docs.openstack.org/developer/swift/"
-            >docs.openstack.org/developer/swift/</link>.</para>
-    <!-- <xi:include href="../common/section_about-object-storage.xml"/> -->
     <xi:include href="section_object-storage-monitoring.xml"/>
 </chapter>

doc/common/app_support.xml

@@ -6,8 +6,8 @@
     <?dbhtml stop-chunking?>
     <title>Community support</title>
 
-    <para>To help you run and use OpenStack, many resources are
+    <para>Many resources are available to help you run and use
-        available. Many OpenStack community members can answer
+        OpenStack. Members of the OpenStack community can answer
         questions and help with bug suspicions. We are constantly
         improving and adding to the main features of OpenStack, but if
         you have any problems, do not hesitate to ask. Use the
@@ -28,7 +28,7 @@
                 >report a bug</link>.</para>
 
         <para>The following books explain how to install an OpenStack cloud
-        and its components:
+        and its associated components:
        </para>
         <itemizedlist>
           <listitem>
@@ -165,26 +165,26 @@
 
     <section xml:id="support-ask_openstack">
         <title>ask.openstack.org</title>
-        <para>During set up or testing, you might have questions about
+        <para>During the set up or testing of OpenStack, you might have questions about
-how to do something or be in a situation where a feature
+how a specific task is completed or be in a situation where a feature
 does not work correctly. Use the <link
     xlink:href="http://ask.openstack.org"
     >ask.openstack.org</link> site to ask questions and
 get answers. When you visit the <link
     xlink:href="http://ask.openstack.org"
     >http://ask.openstack.org</link> site, scan the recently asked questions to see whether
-your question was already answered. If not, ask a new question. Be sure
+your question has already been answered. If not, ask a new question. Be sure
 to give a clear, concise summary in the title and provide
 as much detail as possible in the description. Paste in
-your command output or stack traces, link to screen shots,
+your command output or stack traces, links to screen shots,
 and so on.</para>
     </section>
     <section xml:id="support-mailing-lists">
         <title>OpenStack mailing lists</title>
         <para>A great way to get answers and insights is to post your
-            question or scenario to the OpenStack mailing list. You
+            question or problematic scenario to the OpenStack mailing list. You
-            can learn from and help others who might have the same
+            can learn from and help others who might have similar
-            scenario as you. To subscribe or view the archives, go to
+            issues. To subscribe or view the archives, go to
                 <link
                 xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack"
                 >http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack</link>.
@@ -199,27 +199,26 @@ and so on.</para>
     <section xml:id="support-wiki">
         <title>The OpenStack wiki</title>
         <para>The <link xlink:href="http://wiki.openstack.org/"
-                >OpenStack wiki</link> contains content on a broad
+                >OpenStack wiki</link> contains a broad
-            range of topics but some of it sits a bit below the
+            range of topics but some of the information can be difficult
-            surface. Fortunately, the wiki search feature enables you
+            to find or is a few pages deep. Fortunately, the wiki search
-            to search by title or content. If you search for specific
+            feature enables you to search by title or content. If you
-            information, such as about networking or nova, you can
+            search for specific information, such as about networking or
-            find lots of content. More is being added all the time, so
+            nova, you can find lots of relevant material. More is being
-            be sure to check back often. You can find the search box
+            added all the time, so be sure to check back often. You can find
-            in the upper right corner of any OpenStack wiki
+            the search box in the upper right corner of any OpenStack wiki
             page.</para>
     </section>
     <section xml:id="support-bugs-area">
         <title>The Launchpad Bugs area</title>
-        <para>So you think you've found a bug. That's great!
+            <para>The OpenStack community values your set
-            Seriously, it is. The OpenStack community values your set
             up and testing efforts and wants your feedback. To log a
             bug, you must sign up for a Launchpad account at <link
                 xlink:href="https://launchpad.net/+login"
                 >https://launchpad.net/+login</link>. You can view
             existing bugs and report bugs in the Launchpad Bugs area.
-            Use the search feature to determine whether the bug was
+            Use the search feature to determine whether the bug has
-            already reported (or even better, already fixed). If it
+            already been reported or even better, already fixed. If it
             still seems like your bug is unreported, fill out a bug
             report.</para>
         <para>Some tips:</para>
@@ -230,10 +229,10 @@ and so on.</para>
 <listitem>
     <para>Provide as much detail as possible in the
         description. Paste in your command output or stack
-        traces, link to screen shots, and so on.</para>
+        traces, links to screen shots, and so on.</para>
 </listitem>
 <listitem>
-    <para>Be sure to include the software version that you are using,
+    <para>Be sure to include the software and package versions that you are using,
                     especially if you are using a development branch,
                     such as, <literal>"Grizzly release" vs git commit
                         bc79c3ecc55929bac585d04a03475b72e06a3208</literal>.</para>

doc/common/ch_getstart.xml

@@ -37,9 +37,10 @@
                 <td><link
                     xlink:href="http://docs.openstack.org/developer/horizon/"
                     >Horizon</link></td>
-                <td>Enables users to interact with OpenStack services
+                <td>Provides a web-based self-service portal to interact
-                    to launch an instance, assign IP addresses, set
+                    with underlying OpenStack services, such as launching
-                    access controls, and so on.</td>
+                    an instance, assigning IP addresses and configuring
+                    access controls.</td>
             </tr>
             <tr>
                 <td><link
@@ -48,7 +49,9 @@
                 <td><link
                         xlink:href="http://docs.openstack.org/developer/nova/"
                         >Nova</link></td>
-                <td>Provisions and manages large networks of virtual
+                <td>Manages the lifecycle of compute instances in an
+                    OpenStack environment. Responsibilities include
+                    spawning, scheduling and decomissioning of
                     machines on demand.</td>
             </tr>
             <tr>
@@ -58,12 +61,12 @@
                 <td><link
                         xlink:href="http://docs.openstack.org/developer/neutron/"
                         >Neutron</link></td>
-                <td>Enables network connectivity as a service among
+                <td>Enables network connectivity as a service for
-                    interface devices managed by other OpenStack
+                    other OpenStack services, such as OpenStack Compute.
-                    services, usually Compute. Enables users to create
+                    Provides an API for users to define networks and the
-                    and attach interfaces to networks. Has a pluggable
+                    attachments into them. Has a pluggable architecture
-                    architecture that supports many popular networking
+                    that supports many popular networking vendors and
-                    vendors and technologies.</td>
+                    technologies.</td>
             </tr>
             <tr><th colspan="3" align="center">Storage</th></tr>
             <tr>
@@ -73,8 +76,11 @@
                 <td><link
                     xlink:href="http://docs.openstack.org/developer/swift/"
                     >Swift</link></td>
-                <td>Stores and gets files. Does not mount directories
+                <td>Stores and retrieves arbitrary unstructured
-                    like a file server.</td>
+                    data objects via a RESTful, HTTP based API. It is highly
+                    fault tolerant with its data replication and scale out
+                    architecture. Its implementation is not like a file server
+                    with mountable directories.</td>
             </tr>
             <tr>
                 <td><link
@@ -83,8 +89,10 @@
                 <td><link
                     xlink:href="http://docs.openstack.org/developer/cinder/"
                     >Cinder</link></td>
-                <td>Provides persistent block storage to guest virtual
+                <td>
-                    machines.</td>
+                    Provides persistent block storage to running instances. Its
+                    pluggable driver architecture facilitates the creation and
+                    management of block storage devices.</td>
             </tr>
             <tr><th colspan="3" align="center">Shared services</th></tr>
             <tr>
@@ -94,9 +102,9 @@
                 <td><link
                         xlink:href="http://docs.openstack.org/developer/keystone/"
                         >Keystone</link></td>
-                <td>Provides authentication and authorization for the
+                <td>Provides an authentication and authorization service
-                    OpenStack services. Also provides a service
+                    for other OpenStack services. Provides a catalog of endpoints
-                    catalog within a particular OpenStack cloud.</td>
+                    for all OpenStack services.</td>
             </tr>
             <tr>
                 <td><link
@@ -105,8 +113,10 @@
                 <td><link
                         xlink:href="http://docs.openstack.org/developer/glance/"
                         >Glance</link></td>
-                <td>Provides a registry of virtual machine images.
+                <td>Stores and retrieves virtual machine disk images.
-                    Compute uses it to provision instances.</td>
+                    OpenStack Compute makes use of this during instance
+                    provisioning.
+                </td>
             </tr>
 
             <tr>
@@ -117,7 +127,7 @@
                         xlink:href="http://docs.openstack.org/developer/ceilometer/"
                         >Ceilometer</link></td>
                 <td>Monitors and meters the OpenStack cloud for
-                    billing, benchmarking, scalability, and statistics
+                    billing, benchmarking, scalability, and statistical
                     purposes.</td>
             </tr>
             <tr><th colspan="3" align="center">Higher-level services</th></tr>

doc/common/section_about-object-storage.xml

@@ -5,13 +5,27 @@
     version="5.0"
     xml:id="ch_introduction-to-openstack-object-storage">
     <title>Introduction to Object Storage</title>
-    <para>Object Storage is a scalable object storage system - it is
+    <para>Object Storage is a robust, highly scalable and
-        not a file system in the traditional sense. You cannot mount
+          fault tolerant storage platform for unstructured data
-        this system like traditional SAN or NAS volumes. Because Object
+          such as objects. Objects are stored bits, accessed
-        Storage requires a different way of thinking when it comes to
+          through a RESTful, HTTP-based interface. You cannot access
-        storage, take a few moments to review the key concepts in the
+          data at the block or file level. Object Storage is commonly
-        developer documentation at <link
+          used to archive and back up data, with use cases in
-            xlink:href="http://docs.openstack.org/developer/swift/"
+          virtual machine image, photo, video and music storage.</para>
-            >docs.openstack.org/developer/swift/</link>.</para>
+    <para>Object Storage provides a high degree of availability, throughput,
-    <!-- TODO Is this really the best we can do?-->
+          and performance with its scale out architecture. Each object is
+          replicated across multiple servers, residing within the
+          same data center or across data centers, which mitigates the risk
+          of network and hardware failure. In the event of hardware failure,
+          Object Storage will automatically copy objects to a new location
+          to ensure that there are always three copies available.
+          Object Storage is an eventually consistent distributed storage
+          platform; it sacrifices consistency for maximum
+          availability and partition tolerance. Object Storage enables you to
+          create a reliable platform by using commodity hardware and
+          inexpensive storage.</para>
+    <para>For more information, review the key concepts
+          in the developer documentation at <link
+              xlink:href="http://docs.openstack.org/developer/swift/"
+              >docs.openstack.org/developer/swift/</link>.</para>
 </section>

doc/common/section_keystone-concepts.xml

@@ -97,8 +97,8 @@
         <varlistentry>
             <term><emphasis role="bold">Endpoint</emphasis></term>
             <listitem>
-                <para>An network-accessible address, usually described
+                <para>A network-accessible address, usually described
-                    by URL, from where you access a service. If using
+                    by a URL, from where you access a service. If using
                     an extension for templates, you can create an
                     endpoint template, which represents the templates
                     of all the consumable services that are available