diff --git a/source/clear-linux/reference/collaboration/collaboration.rst b/source/clear-linux/reference/collaboration/collaboration.rst index 2d4f6386..4f924050 100644 --- a/source/clear-linux/reference/collaboration/collaboration.rst +++ b/source/clear-linux/reference/collaboration/collaboration.rst @@ -1,49 +1,43 @@ .. _collaboration: -Documentation contribution guidelines -##################################### +Documentation guidelines +######################## See a missing topic in the documentation? Find an existing document that could be improved? Help us out by contributing! If you haven't contributed before, take a moment to review our `Contribution guidelines`_. -Do you have questions about contributing to the documentation that were not -answered by these guidelines? Send your question to the `mailing list`_ at: +Do you have questions about the documentation that were not answered by these +guidelines? Send your question to the `mailing list`_ at: dev@lists.clearlinux.org. Contribution guidelines *********************** -We welcome contributions and we ask you to follow our guidelines for -consistent, readable documentation. - The |CL| documentation is hosted in GitHub and is written using -reStructuredText. These guidelines provide examples, templates, and best -practices for your contributions. +reStructuredText. Use our guidelines and best practices to write consistent, +readable documentation. -Before contributing -=================== +.. toctree:: + :maxdepth: 1 -If you haven't contributed before, review the following items: - -* GitHub `documentation repository`_ shows our document organization. -* :ref:`writing-guide` describes the style we use to keep our documents clear - and concise. -* :ref:`structure-formatting` provides details on how we use reStructuredText - and Sphinx in our documents. + Writing guide describes the style we use to keep our documents clear and concise. + Structure and formatting guide details how we structure and format our documents using reStructuredText and Sphinx. + GitHub documentation repository shows our document organization. How to contribute -================= +***************** There are multiple ways to contribute and help improve our documentation: * **Make a suggestion**: Have a documentation suggestion but no time to write it - yourself? Send your suggestion to the `mailing list`_ at: dev@lists.clearlinux.org. -* **Log an issue**: If you find a problem in our documentation (such as typos or out-of-date - information), log an issue in the `documentation repository`_. + yourself? Send your suggestion to the `mailing list`_ at: + dev@lists.clearlinux.org. +* **Log an issue**: If you find a problem in our documentation (such as typos or + out-of-date information), log an issue in the `documentation repository`_. * **Contribute directly via GitHub**: Whether you've found a typo, have better - instructions or examples, or have a new page to add, submit your improvement or - addition as a pull request on the `documentation repository`_. + instructions or examples, or have a new page to add, submit your improvement + or addition as a pull request on the `documentation repository`_. * **Test documentation**: Step through our instructional guides and tutorials to verify the instructions. Log or correct any out-of-date information. @@ -74,17 +68,19 @@ Our documentation is hosted in GitHub and we follow the standard `GitHub flow`_: References ********** -We use the following references to guide the grammar, style, and formatting of our -documentation: +We use the following references to guide the grammar, style, and formatting of +our documentation: +* `Microsoft Writing Style Guide`_ +* `Merriam-Webster Dictionary`_ * The Chicago Manual of Style (15th edition), The University of Chicago Press -* Merriam-Webster Dictionary -* Microsoft Manual of Style for Technical Publications, Microsoft Press * Microsoft Press Computer Dictionary, Microsoft Press * Read Me First!, Oracle Technical Publications -* The Merriam-Webster's Collegiate Dictionary + .. _`code of conduct`: https://clearlinux.org/community/code-of-conduct .. _mailing list: https://lists.clearlinux.org/mailman/listinfo/dev .. _GitHub flow: https://guides.github.com/introduction/flow/ .. _documentation repository: https://github.com/clearlinux/clear-linux-documentation +.. _Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/ +.. _Merriam-Webster Dictionary: https://www.merriam-webster.com/ \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/structure-formatting.rst b/source/clear-linux/reference/collaboration/structure-formatting.rst index 1b8a0d5b..ab521891 100644 --- a/source/clear-linux/reference/collaboration/structure-formatting.rst +++ b/source/clear-linux/reference/collaboration/structure-formatting.rst @@ -8,42 +8,41 @@ formatting, and writing style helps readers quickly find what they need and to understand the content more effectively. This document describes our organization and formatting guidelines. -.. contents:: :local: - :depth: 1 - Refer to :ref:`writing-guide` to learn how we keep our documents clear and concise. +.. contents:: :local: + :depth: 1 Markup ****** Our documentation is written in the reStructuredText markup language, using -Sphinx roles and directives. We use Sphinx to generate the final -documentation. You can read more about reStructuredText and Sphinx on their -respective websites: +Sphinx roles and directives. We use Sphinx to generate the final documentation. +You can read more about reStructuredText and Sphinx on their respective +websites: * `Sphinx documentation`_ * `reStructuredText Primer`_ -You can view the content directly in the .rst markup files, or you can -generate the HTML content by installing and running the documentation locally. -To run the documentation locally, follow the instructions found in the +You can view the content directly in the .rst markup files, or you can generate +the HTML content by installing and running the documentation locally. To run the +documentation locally, follow the instructions found in the `documentation repository`_ README. New pages ========= There are a few additional steps to consider when adding a new page to the -documentation. First, identify where your new page should be located within -the existing `Documentation organization`_. Second, make sure the new page -is picked up in the Sphinx build and easily linkable from other content. +documentation. First, identify where your new page should be located within the +existing `Documentation organization`_. Second, make sure the new page is picked +up in the Sphinx build and easily linkable from other content. -Each page must be included in a `Sphinx toctree`_ in order to -be included in the documentation content tree. Typically, pages are added to -the section landing page toctree. +Each page must be included in a `Sphinx toctree`_ in order to be included in the +documentation content tree. Typically, pages are added to the section landing +page toctree. -For example, the "Documentation contribution guidelines" page toctree looks like: +For example, the :ref:`collaboration` page toctree looks like: .. code-block:: rest @@ -53,10 +52,11 @@ For example, the "Documentation contribution guidelines" page toctree looks like writing-guide structure-formatting -Additionally, each page must include a uniquely named reST label directly -before the page title, to enable the `Sphinx ref role`_ for linking to a page. +Additionally, each page must include a uniquely named reST label directly before +the page title, to enable the `Sphinx ref role`_ for linking to a page. -For example, this page "Structure and formating" has the label ``.. _structure-formatting``: +For example, this page "Structure and formating" has the label +``.. _structure-formatting``: .. code-block:: rest @@ -65,8 +65,8 @@ For example, this page "Structure and formating" has the label ``.. _structure-f Structure and formatting ######################## -This page can then be referenced from other pages in the documentation using -the `:ref:` role: +This page can then be referenced from other pages in the documentation using the +`:ref:` role: .. code-block:: rest @@ -77,7 +77,8 @@ Documentation organization The documentation is organized into five general sections: -#. **Concepts**: Introduction and overview of |CL| specific concepts or features. +#. **Concepts**: Introduction and overview of |CL| specific concepts or + features. #. **Get started**: Information about getting started with |CL|. #. **Guides**: Detailed information and instruction on using |CL| features. #. **Tutorials**: Step-by-step instruction for using |CL| in specific use cases. @@ -102,7 +103,8 @@ clarity. * All files must have a top level heading, which is the title for the page. * Headings should be short and descriptive. -* Write headings in sentence case (capitalize only the first word and proper nouns). +* Write headings in sentence case (capitalize only the first word and proper + nouns). * Up to three additional levels of headings are allowed under the title heading. * Each heading must be followed by at least one paragraph of content. There should never be two consecutive headings. @@ -140,8 +142,8 @@ To mark up headings in the .rst file: In-page navigation ================== -If a page has three or more sections, provide quick links to each section. -Place the quick links after the overview section. +If a page has three or more sections, provide quick links to each section. Place +the quick links after the overview section. Use the standard `reST contents directive`_ with depth: 1 for quick links. @@ -149,15 +151,73 @@ Inline text formatting ********************** We use the `Microsoft Writing Style Guide`_ as our starting point for text -formatting. We execute the formatting using reST and Sphinx markup. +formatting. We apply the formatting using reST and Sphinx markup. Use our quick reference for the most commonly used inline text elements: +--------------------------------+---------------------------------------+-----------------------------+ | **Element** | **Convention** | **reST/Sphinx** | +--------------------------------+---------------------------------------+-----------------------------+ +| Acronyms | Spell out first use, with | Use ``:abbr:`` | +| | acronym in parenthesis. | | +| | For all subsequent uses, | | +| | use the acronym. | | ++--------------------------------+---------------------------------------+-----------------------------+ +| Bundle names | Bold | Use the ``:command:`` role. | ++--------------------------------+---------------------------------------+-----------------------------+ +| Callouts | | Use ``.. note::`` | ++--------------------------------+---------------------------------------+-----------------------------+ +| Code/command examples | Monospace, visually distinct | Use ``.. code-block::`` | +| | from rest of text. Use an | with the correct language | +| | indented call-out box. | setting. | ++--------------------------------+---------------------------------------+-----------------------------+ +| Commands | Bold | Use the ``:command:`` role. | ++--------------------------------+---------------------------------------+-----------------------------+ +| Command flags | Bold | Use the ``:command:`` role. | ++--------------------------------+---------------------------------------+-----------------------------+ +| Console output | Monospace, visual distinction | Use ``.. code-block::`` | +| | from rest of text. Use an | with console as the | +| | indented call-out box. | language setting. | ++--------------------------------+---------------------------------------+-----------------------------+ | Emphasis | Italic | ``*strong*`` | +--------------------------------+---------------------------------------+-----------------------------+ +| Environment variables | Use the case format of the | Use ``:envvar:`` | +| | environment variable. | | ++--------------------------------+---------------------------------------+-----------------------------+ +| Example commands with | Use angle brackets for swapping | | +| optional or replaceable | in the specific name, | | +| parts | e.g. . | | +| | | | +| | Use square brackets for optional | | +| | parts, | | +| | e.g. [--build]. | | ++--------------------------------+---------------------------------------+-----------------------------+ +| Example URLs (not linked) | Plain text | | ++--------------------------------+---------------------------------------+-----------------------------+ +| File extensions | Lowercase | | ++--------------------------------+---------------------------------------+-----------------------------+ +| File names, directories, paths | Title style capitalization | Use the ``:file:`` role. | ++--------------------------------+---------------------------------------+-----------------------------+ +| GUI labels | | Use ``:guilabel:`` | ++--------------------------------+---------------------------------------+-----------------------------+ +| Inline comments | | Use ``..`` | ++--------------------------------+---------------------------------------+-----------------------------+ +| Keystrokes | | Use ``:kbd:`` | ++--------------------------------+---------------------------------------+-----------------------------+ +| Local navigation | | ``.. contents:: :local:`` | +| | | with a depth of 1 | ++--------------------------------+---------------------------------------+-----------------------------+ +| Menu selection | | Use ``:menuselection:`` | ++--------------------------------+---------------------------------------+-----------------------------+ +| New terms | Italic for first use, normal for all | ``*term*`` | +| | subsequent use. | | +| | | | +| | If it is used outside of the source | | +| | of definition, link the term. | | ++--------------------------------+---------------------------------------+-----------------------------+ +| Product name | Follow correct trademark and | | +| | attribution guidelines. | | ++--------------------------------+---------------------------------------+-----------------------------+ | Tool names | Correctly capitalized, no quotes, | | | | bold, or italics as the basic rule. | | | | | | @@ -169,64 +229,6 @@ Use our quick reference for the most commonly used inline text elements: | | used at the start of a sentence, use | | | | bold. | | +--------------------------------+---------------------------------------+-----------------------------+ -| Commands | Bold | Use the ``:command:`` role. | -+--------------------------------+---------------------------------------+-----------------------------+ -| Command flags | Bold | Use the ``:command:`` role. | -+--------------------------------+---------------------------------------+-----------------------------+ -| New terms | Italic for first use, normal for all | ``*term*`` | -| | subsequent use. | | -| | | | -| | If it is used outside of the source | | -| | of definition, link the term. | | -+--------------------------------+---------------------------------------+-----------------------------+ -| Bundle names | Bold | Use the ``:command:`` role. | -+--------------------------------+---------------------------------------+-----------------------------+ -| File names, directories, paths | Title style capitalization | Use the ``:file:`` role. | -+--------------------------------+---------------------------------------+-----------------------------+ -| File extensions | Lowercase | | -+--------------------------------+---------------------------------------+-----------------------------+ -| Example URLs (not linked) | Plain text | | -+--------------------------------+---------------------------------------+-----------------------------+ -| Product name | Follow correct trademark and | | -| | attribution guidelines. | | -+--------------------------------+---------------------------------------+-----------------------------+ -| Code/command examples | Monospace, visually distinct | Use ``.. code-block::`` | -| | from rest of text. Use an | with the correct language | -| | indented call-out box. | setting. | -+--------------------------------+---------------------------------------+-----------------------------+ -| Console output | Monospace, visual distinction | Use ``.. code-block::`` | -| | from rest of text. Use an | with console as the | -| | indented call-out box. | language setting. | -+--------------------------------+---------------------------------------+-----------------------------+ -| Acronyms | Spell out first use, with | Use ``:abbr:`` | -| | acronym in parenthesis. | | -| | For all subsequent uses, | | -| | use the acronym. | | -+--------------------------------+---------------------------------------+-----------------------------+ -| Keystrokes | | Use ``:kbd:`` | -+--------------------------------+---------------------------------------+-----------------------------+ -| GUI labels | | Use ``:guilabel:`` | -+--------------------------------+---------------------------------------+-----------------------------+ -| Menu selection | | Use ``:menuselection:`` | -+--------------------------------+---------------------------------------+-----------------------------+ -| Callouts | | Use ``.. note::`` | -+--------------------------------+---------------------------------------+-----------------------------+ -| Local navigation | | ``.. contents:: :local:`` | -| | | with a depth of 1 | -+--------------------------------+---------------------------------------+-----------------------------+ -| Environment variables | Use the case format of the | Use ``:envvar:`` | -| | environment variable. | | -+--------------------------------+---------------------------------------+-----------------------------+ -| Inline comments | | Use ``..`` | -+--------------------------------+---------------------------------------+-----------------------------+ -| Example commands with | Use angle brackets for swapping | | -| optional or replaceable | in the specific name, | | -| parts | e.g. . | | -| | | | -| | Use square brackets for optional | | -| | parts, | | -| | e.g. [--build]. | | -+--------------------------------+---------------------------------------+-----------------------------+ White space and line length =========================== @@ -239,9 +241,9 @@ Remove trailing whitespace from your documents. Code blocks and examples ************************ -When providing example code or commands that are less than 10 lines, use -the `Sphinx code-block directive`_. Use the appropriate syntax highlighting -for the example command or code. +When providing example code or commands that are less than 10 lines, use the +`Sphinx code-block directive`_. Use the appropriate syntax highlighting for the +example command or code. For example, if showing console output, use console highlighting: @@ -259,15 +261,16 @@ as step-by-step instructions. Use a bulleted list when the order of the items is not important. -For both list types, keep all items in the list parallel. See :ref:`parallelism`. +For both list types, keep all items in the list parallel. See +:ref:`parallelism`. Use standard `reST list markup`_. Numbered lists ============== -Numbered lists are most frequently used for procedures. Use numbered lists -to show sequence for the items. Follow our guidelines for numbered lists: +Numbered lists are most frequently used for procedures. Use numbered lists to +show sequence for the items. Follow our guidelines for numbered lists: * Make sure the list is sequential and not just a collection of items. * Introduce a numbered list with a sentence. End the setup text with a @@ -298,20 +301,9 @@ a sequence is not required. Here are some guidelines for bulleted lists: * Avoid interrupting bulleted lists with other paragraph styles. * Second-level bullets are acceptable; avoid third-level bullets. -Use the correct ending punctuation for sentence style bullet lists. For -example: +Use the correct ending punctuation for sentence style bullet lists. For example: -**Incorrect** - - When setting the user code remember: - - * make the user code easy to remember. Use a number that has a meaning - for you - * change the code once a month - * do not disclose the user code to anyone else. This includes the - security company - -**Correct** +**Use this:** When setting the user code, remember: @@ -319,11 +311,20 @@ example: * Change the code once a month. * Do not disclose the user code to anyone, including the security company. +**Not this:** + + When setting the user code remember: + + * make the user code easy to remember. Use a number that has a meaning for you + * change the code once a month + * do not disclose the user code to anyone else. This includes the security + company + Instructions ============ -When presenting instructions, such as in a tutorial, present them in a -numbered list according to these guidelines: +When presenting instructions, such as in a tutorial, present them in a numbered +list according to these guidelines: * Each step (list item) should describe one action. @@ -346,79 +347,67 @@ numbered list according to these guidelines: Notices ******* -We use four special types of notices: notes, cautions, warnings, and -dangers. Here are some specific rules and tips regarding use of these -notices: +We use four special types of notices: notes, cautions, warnings, and dangers. +Here are some specific rules and tips regarding use of these notices: -* Do not use a notice directly after a heading. Notices must follow a - variant of body text. +* Do not use a notice directly after a heading. Notices must follow a variant of + body text. * Do not include more than one notice in a single notice block. * Avoid back-to-back notices. -* If back-to-back notices are not avoidable, make sure each distinct - notice in the notice block is clearly defined. +* If back-to-back notices are not avoidable, make sure each distinct notice in + the notice block is clearly defined. Use the standard `reST admonition directive`_. -Notes, cautions, warnings, and dangers -====================================== +Notes, cautions, and warnings +============================= -Use notes sparingly. Avoid having more than one note per section. If -you exceed this number consistently, consider rewriting the notes as -main body text. +Use notes sparingly. Avoid having more than one note per section. If you exceed +this number consistently, consider rewriting the notes as main body text. -Use cautions, warnings, and dangers to alert readers of potential -problems or pitfalls. Use conditional phrases in cautions and warnings, -such as "If you do X, then Y will occur." +Use cautions and warnings to alert readers of potential problems or pitfalls. +Use conditional phrases in cautions and warnings, such as "If you do X, then Y +will occur." These are examples of typical notices and the conditions for their usage: .. note:: - Notes are extra bits of information, supplementary to the main - flow. Notes should be relatively short. If the note content is - a short paragraph, consider rewriting the note as body text. + Notes are extra bits of information that supplement the main content. Notes + should be relatively short. .. caution:: - Cautions are low-level hazard messages that alert the user of - possible equipment, product, and software damage, including loss - of data. + Cautions are low-level hazard messages that alert the user of possible + equipment, product, and software damage, including loss of data. .. warning:: - Warnings are mid-level hazards that are likely to cause product - damage as well as bodily injury to humans. The most common warning - is for electrical hazards. - -.. danger:: - Dangers are high-level hazards that are likely to cause product - damage as well as bodily injury and even death to humans. + Warnings are mid-level hazards that are likely to cause product damage. Links ***** Use the standard `reST markup for links`_. -To add a link to another documentation page, use the `:ref:` role: +To add a cross-reference to another documentation page, use the `:ref:` role: .. code-block:: rest :ref:`structure-formatting` -To add an external link, we use named references that refer to a defined link/label -at the bottom of the page. +To add an external link, we use named references that refer to a defined +link/label at the bottom of the page. -For example, a link is defined at the bottom of the page like this: +For example, an external link is defined at the bottom of the page like this: .. code-block:: rest .. _wiki about dogs: https://en.wikipedia.org/wiki/Dog -The same link is used in the content like this: +The defined link is then used in the content like this: .. code-block:: rest Check out the great `wiki about dogs`_. - - Images ****** @@ -440,8 +429,8 @@ Follow these guidelines when using graphics in support of your documentation: * Place the image immediately after the text it helps clarify, or as close as possible. -* Use the `Sphinx figure directive`_ to insert images and figures into the document. - Include both alt text and a figure name and caption. +* Use the `Sphinx figure directive`_ to insert images and figures into the + document. Include both alt text, a figure name, and caption. For example: diff --git a/source/clear-linux/reference/collaboration/writing-guide.rst b/source/clear-linux/reference/collaboration/writing-guide.rst index 3f9a03f1..fcdac0a2 100644 --- a/source/clear-linux/reference/collaboration/writing-guide.rst +++ b/source/clear-linux/reference/collaboration/writing-guide.rst @@ -3,28 +3,23 @@ Writing guide ############# -We want our documentation to be easy to read and understand. This -document describes guidelines for writing documentation that is -clear, concise, confident, and courteous. - -Refer to :ref:`structure-formatting` for details on how we use reStructuredText -and Sphinx in our documents. - -This document contains the following sections: +We want our documentation to be easy to read and understand. This document +describes guidelines for writing documentation that is clear, concise, +confident, and courteous. +Refer to :ref:`structure-formatting` for details on organizing content and how +we use reStructuredText and Sphinx. .. contents:: :local: :depth: 1 - - Use simple English ****************** Write using simple English: Be brief and communicate only the information that is needed. Be friendly and informative. Emphasize clarity and avoid -complicated or technical terms. Make the content accessible to non-native -speakers. +unecessary complicated or technical terms. Make the content accessible to +non-native speakers. Be brief ======== @@ -37,24 +32,24 @@ Introduction, body, and conclusion. Be friendly =========== -We write for our peers and want to be familiar. Use the second person, -you or we. Be professional, respectful, and cooperative. +We write for our peers and want to be familiar. Use the second person, you or +we. Be professional, respectful, and cooperative. -Assume your audience has the same level of technical understanding and -expertise as you did when you first started collaborating. Do not talk -down to our readers, but also do not assume they know everything about -the subject. Offer brief explanations or summaries of common knowledge -if a significant portion of readers might benefit. +Assume your audience has the same level of technical understanding and expertise +as you did when you first started collaborating. Do not talk down to our +readers, but also do not assume they know everything about the subject. Offer +brief explanations or summaries of common knowledge if a significant portion of +readers might benefit. Use simple words ================ -Use simple words to increase reader comprehension and reduce ambiguity. -Follow our tips for making good word choices: +Use simple words to increase reader comprehension and reduce ambiguity. Follow +our tips for making good word choices: -* **Avoid jargon**: Write for your audience, using everyday language - where possible, and technical terms where appropriate. Avoid clichés, - idioms, and metaphors. +* **Avoid jargon**: Write for your audience, using everyday language where + possible, and technical terms where appropriate. Avoid clichés, idioms, and + metaphors. * **Be consistent**: Use one term for each concept or action and use it consistently. * **Avoid "fancy" words and phrases**: If there is a simpler word or phrase, @@ -82,42 +77,39 @@ Use product names only when necessary. Typically, you can rewrite sentences to remove the product name with no change in meaning, which keeps the content concise and scannable. -Avoid using the product name in page titles and headings. Keep page -titles and headings concise and descriptive of the topic. +Avoid using the product name in page titles and headings. Make content scannable ********************** -Organize your content to make it scannable for the reader, which -helps them find what they need quickly, and helps them understand more -efficiently. +Organize your content to make it scannable for the reader, which helps them find +what they need quickly, and helps them understand more efficiently. -* **Put the most important content first.** Make sure your introduction - clearly communicates what the reader can find on the page. Organize - supporting information towards the end of the page. +* **Put the most important content first.** Make sure your introduction clearly + communicates what the reader can find on the page. Organize supporting + information towards the end of the page. * **Write scannable headings.** Think of headings as the outline for your content. Write headings that are short, specific, and use `Parallelism`_. Top level headings should show the most important subjects on the page. -* **Write great link text.** Great link text tells the reader what they - can expect when they click on a link. It also helps make the page more - scannable. Follow our guidelines for writing `Link text`_. +* **Write great link text.** Great link text tells the reader what they can + expect when they click on a link. It also helps make the page more scannable. + Follow our guidelines for writing `Link text`_. Link text ========= All links in content should follow these guidelines: -* **Write descriptive link text**: Link text should describe where the - link goes, without having to read the surrounding text. -* **Keep link text concise**: Use only the words needed to accurately - describe the destination. -* **Use unique link text**: Each link on a page should be unique. If users - see the same link text twice on a page, they'll assume it goes to the - same place. +* **Write descriptive link text**: Link text should describe where the link + goes, without having to read the surrounding text. +* **Keep link text concise**: Use only the words needed to accurately describe + the destination. +* **Use unique link text**: Each link on a page should be unique. If users see + the same link text twice on a page, they'll assume it goes to the same place. * **Start link text with keywords**: Frontload the link text with the most important words to help users scan the text. -* **Avoid generic text**: Don't use generic, uninformative link text such - as "click here" or "read more". +* **Avoid generic text**: Don't use generic, uninformative link text such as + "click here" or "read more". For example: @@ -129,14 +121,14 @@ For example: Use strong verbs **************** -Passive verbs make writing stuffy and formal. Use strong verbs to get to -the point and avoid unnecessary words and phrases. +Passive verbs make writing stuffy and formal. Use strong verbs to get to the +point and avoid unnecessary words and phrases. Use imperatives =============== -Commands, also called imperatives, are the fastest and most direct way of -giving someone instructions. +Commands, also called imperatives, are the fastest and most direct way of giving +someone instructions. For example: @@ -320,17 +312,6 @@ For example: * Widget Pro version 5.0 * Widget Master v2.1.12 -Terms using a hyphen or slash ------------------------------ - -Capitalize only the first letter of terms using a hyphen or slash, even if they -are headings. - -For example: - -* Day/night Menu -* Follow-up Action Items - Contractions ============ @@ -365,32 +346,5 @@ For example: **Not this:** Mom, Dad and I are going to the game. -Commas in numbers ------------------ - -Use commas to divide large numbers into sets of three digits. Use periods for -decimal points. - -Colons ":" ----------- - -If the text following a colon is a sentence, capitalize the first word after the -colon. If the text after a colon is not a sentence, do not capitalize the first -term unless it is a title. - -For example: - -* This is a capitalization example: Donuts do not cause holes. - -* These is a non-capitalization example: colons, semicolons, and commas. - -Use a colon at the end of a sentence or phrase that introduces examples, a list, -a path, user input, or code. - -Do not use a colon to introduce graphics, tables, or sections. - -Do not use a colon at the end of a task title or heading. - - .. _click here: https://en.wikipedia.org/wiki/Dog .. _dog wiki article: https://en.wikipedia.org/wiki/Dog