From 11a0e343865f075c87e19cd690ae7972db538fe7 Mon Sep 17 00:00:00 2001 From: "Jose A. Lopes" Date: Mon, 13 Jan 2014 13:37:06 +0100 Subject: [PATCH] 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 Reviewed-by: Jose A. Lopes --- doc/glossary.rst | 81 +++++++++++++++++++++++++----------------------------- doc/index.rst | 40 +++++++++++++++------------ 2 files changed, 60 insertions(+), 61 deletions(-) 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 : -- 1.7.10.4