diff --git a/doc/contributor-guide/source/writing-style.rst b/doc/contributor-guide/source/writing-style.rst index 58ff795516..523d7df642 100644 --- a/doc/contributor-guide/source/writing-style.rst +++ b/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 diff --git a/doc/contributor-guide/source/writing-style/lists.rst b/doc/contributor-guide/source/writing-style/lists.rst new file mode 100644 index 0000000000..43081c23e1 --- /dev/null +++ b/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. diff --git a/doc/contributor-guide/source/writing-style/num_and_units_of_measure.rst b/doc/contributor-guide/source/writing-style/num_and_units_of_measure.rst new file mode 100644 index 0000000000..f074274f6f --- /dev/null +++ b/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. diff --git a/doc/contributor-guide/source/writing-style/punctuation.rst b/doc/contributor-guide/source/writing-style/punctuation.rst new file mode 100644 index 0000000000..beae89a764 --- /dev/null +++ b/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."