Remove heading guidelines for the Operations Guide, since we decided at the Austin Design Summit to no longer publish with O'Reilly. Change-Id: Ic341951974fbf8df495c5d5b061f6b090ed2a618 Implements: blueprint contributor-guide-reorg
2.1 KiB
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 and table titles
General guidelines
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.
- Add some introductory text between two headings that go directly after each other.
For details on RST formatting, see cg_titles
.
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
- Testing Ceph and OpenStack interoperability
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 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.
For details on RST formatting, see rst_tables
and rst_figures
.