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:
Figure and table titles
Use the following guidelines for all types of headings:
Use sentence-style capitalization.
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.
Do not use double backticks(``) to highlight something.
Add some introductory text between two headings that go directly after each other.
For details on RST formatting, see Titles.
Write the section title in gerund where possible.
If a subsection contains a sub-subsection, start the title of the subsection with a verb in gerund or a noun.
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.
Maintaining your environment
Start the task topic title with an imperative verb.
Add a node
Remove a node
Figure and table titles¶
Follow these guidelines for figure and table titles:
When introducing a table, figure, or diagram, add a short descriptive title.
Do not add the word Table, Diagram, or Figure to the title.
Do not number tables, figures, or diagrams.
Place the title above tables, figures, or diagrams.
Make the title font bold.
Screenshots do not require titles.