Merge "[Contributor Guide] Writing style, new sections added"

doc/contributor-guide/source/writing-style.rst

@@ -14,6 +14,9 @@ throughout all technical publications.
 
    writing-style/general-writing-guidelines.rst
    writing-style/word-choice.rst
+   writing-style/punctuation.rst
+   writing-style/lists.rst
+   writing-style/num_and_units_of_measure.rst
    writing-style/openstack-components.rst
    writing-style/release-names.rst
    writing-style/ui-terminology.rst

doc/contributor-guide/source/writing-style/lists.rst

@@ -0,0 +1,44 @@
+=====
+Lists
+=====
+
+When reading a document for the first time, users scan through pages stopping
+only on the content that stands out, such as titles, lists, links, diagrams,
+and so on. Lists help to organize options, as well as help readers to find
+information easily.
+
+When listing items, follow these guidelines:
+
+* Use a **bulleted list** for options. Create a bulleted list when you need
+  to describe more than three options.
+* Use a **numbered list** for steps.
+* Use a **definition list** to explain terms or describe command-line
+  parameters, options, or arguments.
+* Use a colon at the end of the sentence that introduces a list.
+* Use the same grammatical structure (aka parallel structure) for all items
+  in a list.
+* Start each option with a capital letter.
+
+When listing options in a paragraph, add *and* or *or* before the last item
+in a list. Use a serial (Oxford) comma before these conjunctions if they
+connect three or more items.
+
+Punctuation in lists
+~~~~~~~~~~~~~~~~~~~~
+
+In bulleted lists:
+
+* If you list individual words or phrases, do not add a period at the end
+  of each list item.
+
+* If you use full sentences, add a period at the end of each sentence.
+
+* If your list includes both individual words or phrases and full sentences,
+  be consistent and either add or do not add periods to all items.
+
+In numbered lists:
+
+* Add periods at the end of steps.
+
+* If an item of a numbered list is followed by a code block that illustrates
+  how to perform the step, use a colon at the end.

doc/contributor-guide/source/writing-style/num_and_units_of_measure.rst

@@ -0,0 +1,33 @@
+============================
+Numbers and units of measure
+============================
+
+When using numbers in running text, follow these guidelines:
+
+* Spell out numbers from one to nine. However, use numerals for units
+  of measure.
+* Use Arabic numerals for numbers above ten.
+* If a numeral starts a sentence, spell it out. For example: *Five thousand
+  environments have been deployed during the last six months.*
+* In one sentence, use either a spelled-out number or a numeral, not both.
+* Use a comma if a numeral includes more than 4 digits. For example: *50,000*.
+
+In mathematical expressions:
+
+* Use the *x* symbol for multiplication.
+* Add a space between numbers and operators. For example: *256 x 2 = 512*.
+
+When using units of measure in running text, follow these guidelines:
+
+* Use the corresponding unit symbol if a unit of measure comes immediately
+  after a numeral.
+
+  * **Kb** for kilobit
+  * **KB** for kilobyte
+  * **kbps** for kilobits per second
+  * **GB** for gigabyte
+  * **Gbit** for gigabit
+  * **MB** for megabyte
+
+* Do not pluralize an abbreviated unit of measure.
+* Add a space between a numeral and a unit of measure.

doc/contributor-guide/source/writing-style/punctuation.rst

@@ -0,0 +1,44 @@
+===========
+Punctuation
+===========
+
+Use standard U.S. English rules of punctuation. The table includes some
+general recommendations on the punctuation marks usage based on common
+mistakes made by contributors.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 25 15
+
+   * - Punctuation mark
+     - How to use
+     - Example
+
+   * - Serial (Oxford) comma
+     - Use comma before the *and* and *or* conjunctions that connect items
+       in series of three or more.
+     - You can create, update, and delete roles.
+
+   * - Semicolon
+     - Avoid using semicolons in sentences. Use periods or a commas instead.
+       Use semicolons only to separate series of words separated by commas.
+     - Large, medium, or small; soft or hard; black, gray, or white.
+
+   * - Colon
+     - Use colons to introduce lists and code examples or tables where
+       needed. Do not use colons in headings if this is not explicitly
+       required. Typically, use lowercase letters after colons
+       in running text.
+     - The configuration values are:
+
+       * ``certfile``
+       * ...
+
+   * - Quotation marks
+     - Generally, avoid using quotation marks, use the corresponding markup
+       instead.
+
+       Though, if the quotation marks are required, place commas and periods
+       inside closing quotation marks.
+       These applies to both words-as-words and sentence fragments.
+     - The screen displays, "Hello, world."