commit 11a0e343865f075c87e19cd690ae7972db538fe7
Author: Jose A. Lopes <jabolopes@google.com>
Date:   Mon Jan 13 13:37:06 2014 +0100

    Technical writing: improve documentation and glossary
    
    Improve structure and content on the main documentation page of Ganeti
    and the glossary.
    
    Signed-off-by: Betsy Beyer <bbeyer@google.com>
    Reviewed-by: Jose A. Lopes <jabolopes@google.com>

diff --git a/doc/glossary.rst b/doc/glossary.rst
index f1c255e..77008c2 100644
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -8,78 +8,73 @@ Glossary
   :sorted:
 
   ballooning
-    A term describing runtime, dynamic changes to an instance's memory,
-    without having to reboot the instance. Depending on the hypervisor
-    and configuration, the changes need to be initiated manually, or
-    they can be automatically initiated by the hypervisor based on the
-    node and instances memory usage.
+    A term describing dynamic changes to an instance's memory while the instance
+    is running that don't require an instance reboot. Depending on the
+    hypervisor and configuration, changes may be automatically initiated by the
+    hypervisor (based on the memory usage of the node and instance), or may need
+    to be initiated manually.
 
   BE parameter
-    BE stands for *backend*. BE parameters are hypervisor-independent
-    instance parameters such as the amount of RAM/virtual CPUs it has
-    been allocated.
+    BE stands for *backend*. BE parameters are hypervisor-independent instance
+    parameters, such as the amount of RAM/virtual CPUs allocated to an instance.
 
   DRBD
-    A block device driver that can be used to build RAID1 across the
-    network or even shared storage, while using only locally-attached
-    storage.
+    A block device driver that can be used to build RAID1 across the network or
+    across shared storage, while using only locally-attached storage.
 
   HV parameter
-    HV stands for *hypervisor*. HV parameters are the ones that describe
-    the virtualization-specific aspects of the instance; for example,
-    what kernel to use to boot the instance (if any), or what emulation
-    model to use for the emulated hard drives.
+    HV stands for *hypervisor*. HV parameters describe the virtualization-
+    specific aspects of the instance. For example, a HV parameter might describe
+    what kernel (if any) to use to boot the instance or what emulation model to
+    use for the emulated hard drives.
 
   HVM
-    Hardware virtualization mode, where the virtual machine is oblivious
-    to the fact that's being virtualized and all the hardware is
+    *Hardware Virtualization Mode*. In this mode, the virtual machine is
+    oblivious to the fact that it is virtualized and all its hardware is
     emulated.
 
   LogicalUnit
-    The code associated with an :term:`OpCode`, e.g. the code that
+    The code associated with an :term:`OpCode`; for example, the code that
     implements the startup of an instance.
 
   LUXI
-     Local UniX Interface. The IPC method over :manpage:`unix(7)`
-     sockets used between the CLI tools/RAPI daemon and the master
-     daemon.
+     Local UniX Interface. The IPC method over :manpage:`unix(7)` sockets used
+     between the CLI tools/RAPI daemon and the master daemon.
 
   OOB
-    *Out of Band*. This term describes methods of accessing a machine
-    (or parts of a machine) not via the usual network connection. For
-    example, accessing a remote server via a physical serial console or
-    via a virtual one IPMI counts as out of band access.
+    *Out of Band*. This term describes methods of accessing a machine (or parts
+    of a machine) by means other than the usual network connection.  Examples
+    include accessing a remote server via a physical serial console or via a
+    virtual console. IPMI is also considered OOB access.
 
   OpCode
-    A data structure encapsulating a basic cluster operation; for
-    example, start instance, add instance, etc.
+    A data structure encapsulating a basic cluster operation; for example: start
+    instance, add instance, etc.
 
   PVM
-    (Xen) Para-virtualization mode, where the virtual machine knows it's
-    being virtualized and as such there is no need for hardware
-    emulation or virtualization.
+    (Xen) *Para-virtualization mode*. In this mode, the virtual machine is aware
+    that it is virtualized; therefore, there is no need for hardware emulation
+    or virtualization.
 
   SoR
     *State of Record*. Refers to values/properties that come from an
-    authoritative configuration source. For example, the maximum VCPU
-    over-subscription ratio is a *SoR* value, but the current
-    over-subscription ration (based on how many instances live on the
-    node) is a :term:`SoW` value.
+    authoritative configuration source. For example, the maximum VCPU over-
+    subscription ratio is a SoR value, but the current over-subscription ratio
+    (based upon how many instances live on the node) is a :term:`SoW` value.
 
   SoW
-    *State of the World*. Refers to values that describe directly the
-    world, as opposed to values that come from the
-    configuration. Contrast with :term:`SoR`.
+    *State of the World*. Refers to values that directly describe the world, as
+    opposed to values that come from the configuration (which are considered
+    :term:`SoR`).
 
   tmem
-    Xen Transcendent Memory
-    (http://en.wikipedia.org/wiki/Transcendent_memory). It is a
-    mechanism used by Xen to provide memory over-subscription.
+    Xen Transcendent Memory (http://en.wikipedia.org/wiki/Transcendent_memory).
+    tmem is a mechanism used by Xen to provide memory over-subscription.
 
   watcher
-    :command:`ganeti-watcher` is a tool that should be run regularly
-    from cron and takes care of restarting failed instances, restarting
-    secondary DRBD devices, etc. For more details, see the man page
+    :command:`ganeti-watcher` is a tool that should be run regularly from
+    cron. The tool executes tasks such as restarting failed instances and
+    restarting secondary DRBD devices. For more details, see the man page
     :manpage:`ganeti-watcher(8)`.
 
 
diff --git a/doc/index.rst b/doc/index.rst
index 70b93af..0815efb 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -4,8 +4,9 @@
 Welcome to Ganeti's documentation!
 ==================================
 
-This page is the starting point for browsing the Ganeti documentation. It
-contains links to all the sections of Ganeti documentation, grouped by topic.
+This page is the starting point for browsing the Ganeti
+documentation. Below, the corpus of Ganeti documentation is grouped by
+topic.
 
 A few quick references:
 
@@ -16,29 +17,29 @@ A few quick references:
 Installing Ganeti
 +++++++++++++++++
 
-There are a few resources you can use to install and/or upgrade Ganeti:
+Use the following resources to install and/or upgrade Ganeti:
 
 - :doc:`install`: Comprehensive instructions for installing Ganeti.
 - :doc:`install-quick`: A shortened installation guide for the experienced Ganeti user.
-- :doc:`upgrade`: Instructions for upgrading an existing installation to the latest version of Ganeti.
+- :doc:`upgrade`: Instructions for upgrading an existing Ganeti installation to the latest version.
 
 Using Ganeti
 ++++++++++++
 
 The following resources provide guidance on how to use Ganeti:
 
-- :doc:`admin`: Information about how to manage a Ganeti cluster after it is installed (including management of nodes, instances, and information about the tools and the monitoring agent).
-- :doc:`walkthrough`: A more example-oriented guide to Ganeti.
+- :doc:`admin`: Information about how to manage a Ganeti cluster after it is installed (including management of nodes and instances, and information about Ganeti's tools and monitoring agent).
+- :doc:`walkthrough`: An example-oriented guide to Ganeti.
 - :doc:`manpages`: Descriptions of the various tools that are part of Ganeti.
 - :doc:`security`: A description of the security model underlying a Ganeti cluster.
-- :doc:`hooks`: Information on hooking scripts, which extend Ganeti functionalities by automatically activating when certain events happen.
-- :doc:`iallocator`: Description of the API for external tools which can allocate instances either manually or automatically.
-- :doc:`rapi`: Details the Ganeti remote API, which allows programmatic access to most of the functionalities of Ganeti.
-- :doc:`ovfconverter`: Provides compatibility with the standard OVF virtual machine interchange format.
-- :doc:`virtual-cluster`: Describes how to use virtual cluster support, which is utilized mainly for testing reasons.
+- :doc:`hooks`: Information on hooking scripts, which extend Ganeti functionalities by automatically activating when certain events occur.
+- :doc:`iallocator`: Description of the API for external tools, which can allocate instances either manually or automatically.
+- :doc:`rapi`: Description of the Ganeti remote API, which allows programmatic access to most of the functionalities of Ganeti.
+- :doc:`ovfconverter`: Description of a tool that provides compatibility with the standard OVF virtual machine interchange format.
+- :doc:`virtual-cluster`: Explanation of how to use virtual cluster support, which is utilized mainly for testing reasons.
 
-A few functionalities are explicitly targeted for big installations, in which
-multiple clusters are present.
+Some features are explicitly targeted for large Ganeti installations,
+in which multiple clusters are present:
 
 - :doc:`cluster-merge`: Describes a tool for merging two existing clusters.
 - :doc:`move-instance`: Describes how to move instances between clusters.
@@ -46,18 +47,19 @@ multiple clusters are present.
 Developing Ganeti
 +++++++++++++++++
 
-There are a few useful documents for developers who want to modify Ganeti:
+There are a few documents particularly useful for developers who want
+to modify Ganeti:
 
-- :doc:`locking`: Describes Ganeti's locking strategy and, in particular, lock order dependencies.
+- :doc:`locking`: Describes Ganeti's locking strategy and lock order dependencies.
 - :doc:`devnotes`: Details build dependencies and other useful development-related information. 
 
 
 Implemented designs
 -------------------
 
-Before actual implementation, all Ganeti features are described in a design
-document. Designs fall into two categories: released versions and draft versions
-(which are either incomplete or not implemented).
+Before actual implementation, all Ganeti features are described in a
+design document. Designs fall into two categories: released versions
+and draft versions (which are either incomplete or not implemented).
 
 .. toctree::
    :maxdepth: 1
@@ -124,3 +126,5 @@ Draft designs
    upgrade.rst
    virtual-cluster.rst
    walkthrough
+
+.. vim: set textwidth=72 :
