From 0fca096dfba5f10bc095dabdfbb91463160da902 Mon Sep 17 00:00:00 2001
From: Maria Zlatkova <mzlatkova@mirantis.com>
Date: Sat, 2 Apr 2016 17:06:55 +0300
Subject: [PATCH] [Contributor Guide] Headings

Adds the Headings section to the Writing style subsection
of the Contributor Guide.

Change-Id: Ia42605bf003ca7d71a484b044434a1b476de6aca
Closes-Bug: #1524337
---
 .../source/writing-style.rst                  |  1 +
 .../source/writing-style/headings.rst         | 89 +++++++++++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 doc/contributor-guide/source/writing-style/headings.rst

diff --git a/doc/contributor-guide/source/writing-style.rst b/doc/contributor-guide/source/writing-style.rst
index 523d7df642..76ea2263c9 100644
--- a/doc/contributor-guide/source/writing-style.rst
+++ b/doc/contributor-guide/source/writing-style.rst
@@ -15,6 +15,7 @@ throughout all technical publications.
    writing-style/general-writing-guidelines.rst
    writing-style/word-choice.rst
    writing-style/punctuation.rst
+   writing-style/headings.rst
    writing-style/lists.rst
    writing-style/num_and_units_of_measure.rst
    writing-style/openstack-components.rst
diff --git a/doc/contributor-guide/source/writing-style/headings.rst b/doc/contributor-guide/source/writing-style/headings.rst
new file mode 100644
index 0000000000..8b230863c2
--- /dev/null
+++ b/doc/contributor-guide/source/writing-style/headings.rst
@@ -0,0 +1,89 @@
+.. _headings:
+
+========
+Headings
+========
+
+Readers use the table of contents or scan through the headings to find the
+required content. Therefore, headings must reflect the information that the
+readers search. The OpenStack documentation includes the following types of
+headings:
+
+* Section titles
+* Topic titles
+* Figure titles
+* Table titles
+
+General guidelines
+~~~~~~~~~~~~~~~~~~
+
+Use the following guidelines for all types of headings:
+
+* Use sentence-style capitalization except for the Operations Guide, which
+  follows the `O'Reilly heading capitalization style <http://chimera.labs.oreilly.com/books/1230000000969/ch02.html#headings>`_,
+  and book titles.
+* Make headings brief but descriptive.
+* Use articles in titles, but do not start the title with an article.
+* Avoid using uncommon abbreviations.
+* Do not end a title with a period or colon.
+* Add some introductory text between two headings that go directly after each
+  other.
+
+Section titles
+~~~~~~~~~~~~~~
+
+Write the section title in gerund where possible.
+
+**Examples:**
+
+* Monitoring performance
+* Managing resources
+
+Subsection titles
+~~~~~~~~~~~~~~~~~
+
+If a subsection contains a sub-subsection, start the title of the subsection
+with a verb in gerund or a noun.
+
+**Example:**
+
+* Testing the OpenStack environment
+
+  * Testing Ceph and OpenStack interoperability
+
+    * Test Ceph and Glance
+    * Test Ceph and Cinder
+    * Test Ceph and Rados GW
+    * Test Ceph and Swift
+
+Start the subsection or sub-subsection with a noun or an adjective if it is a
+concept or a reference topic.
+
+**Example:**
+
+* Maintaining your environment
+
+  * General considerations
+
+Topic titles
+~~~~~~~~~~~~
+
+Start the task topic title with an imperative verb.
+
+**Examples:**
+
+* Add a node
+* Remove a node
+
+Figure titles
+~~~~~~~~~~~~~
+
+When introducing a figure or a diagram, add a title. Do not number the
+diagrams. Do not add the word *Diagram* or *Figure* to the title. Do not add a
+period after the title. Screenshots do not require titles.
+
+Table titles
+~~~~~~~~~~~~
+
+When introducing a table, always add a short descriptive title to the table.
+Do not add the word *Table* to the table title.