Merge "[Contributor Guide] Headings"

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

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.