Documentation/Guide conventions

The following lists conventions used for writing specific guides. In general we want to be consistent between guides, especially since some guides include the same files.

General

 * Mentioning Bugs. If there is a bug that causes some workaround or limitation to be documented, the link to the bug report should be included. This makes it easier to maintain and update such notes.

Installation Guide
1) Run the following command to install the components:   a) apt-get install package1 package2 1) Edit the /etc/abc/abc.conf file:   a) Configure database access in the [database] section: [database] ...       connection = mysql:// b) Configure RabbitMQ message broker access in the [DEFAULT] section:       [DEFAULT]        ...        rabbit_host = controller    c) Configure Identity service access in the [keystone_authtoken] section: [keystone_authtoken] ...       auth_host = controller  To configure the Orchestration components Edit the /etc/heat/heat.conf file and perform the following tasks: Configure database access in the [database] section. Replace HEAT_DBPASS with the password you chose for the Orchestration database. [database] ... connection = mysql://heat: HEAT_DBPASS @ controller /heat  Configure RabbitMQ message broker access in the [DEFAULT] section: Replace RABBIT_PASS with the password you chose for the guest account in     RabbitMQ. [DEFAULT] ... rpc_backend = heat.openstack.common.rpc.impl_kombu rabbit_host = controller rabbit_password = RABBIT_PASS
 * Use  instead of the controller node management interface IP address 10.0.0.11. Use replaceable for it like.
 * Use  instead of the compute node management interface IP address for compute nodes. Replace X with a number starting from 1. The management interface IP address of the first compute node is 10.0.0.31, the second is 10.0.0.32, etc.
 * Use  instead of the block storage node management interface IP address for block storage nodes. Replace X with a number starting from 1. The management interface IP address of the first block storage node is 10.0.0.41, the second 10.0.0.42, etc.
 * Use  instead of the object storage node management interface IP address for object storage nodes. Replace X with a number starting from 1. The management interface IP address of the first object storage node is 10.0.0.51, the second 10.0.0.52, etc.
 * For Juno and beyond on Fedora/RHEL/CentOS, use systemctl rather than service restart or chkconfig on, for example, due to the upgrade to version 7.
 * Try to reference the name of a network interface as described in the architecture chapter. For example, say "configure the management interface IP address as 10.0.0.51" rather than "configure eth0 as 10.0.0.51".
 * The example IP addressing structure allows up to 10 controller nodes, network nodes, compute nodes, block storage nodes, and object storage nodes.
 * Database passwords are written as, e.g.
 * Keystone passwords are written as, e.g.
 * is
 * Networking services
 * Use "OpenStack Networking (neutron)" for chapter/section titles and first instance. Use "OpenStack Networking" or "Networking" for additional instances.
 * Use "legacy networking (nova-network)" for chapter/section titles and first instance. Use "legacy networking" for additional instances.
 * Structure for steps that involve commands:
 * Structure for steps that involve configuration:
 * Example code snippet for editing /etc/heat/heat.conf:

Operations Guide
The Operations Guide follows for some cases the O'Reilly style guide.

Official book titles and title abbreviations
The titles are for the HTML and PDF outputs. The title abbreviations are for the PDF output only.

Installation guides
Audience: Cloud operators

Administration guides
Audience: Cloud operators

Application developer and user guides
Audiences:
 * Developers who build applications that run in the cloud
 * Users who manage resources and services in the cloud

Note:

The product definition in the pom.xml file affects the way the title breaks on the cover page in the PDF.

Titles: