diff --git a/source/clear-linux/reference/collaboration/collaboration.rst b/source/clear-linux/reference/collaboration/collaboration.rst index 8b4f76cf..2d4f6386 100644 --- a/source/clear-linux/reference/collaboration/collaboration.rst +++ b/source/clear-linux/reference/collaboration/collaboration.rst @@ -8,29 +8,29 @@ 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 our guidelines? Send your question to the `mailing list`_ at: dev@lists.clearlinux.org. +answered by these guidelines? Send your question to the `mailing list`_ at: +dev@lists.clearlinux.org. Contribution guidelines *********************** -We welcome all contributions to our documentation. For all contributions, -please follow our guidelines for consistent, readable documentation. +We welcome contributions and we ask you to follow our guidelines for +consistent, readable documentation. -For new content, it is important to understand how Sphinx works and how the -documentation is organized and structured. +The |CL| documentation is hosted in GitHub and is written using +reStructuredText. These guidelines provide examples, templates, and best +practices for your contributions. Before contributing =================== -If you haven't contributed before, take the time to get familiar with the existing -documentation and organization (link). Make sure you are familiar with our writing and -formatting guidelines, as well as basic reStructuredText and Sphinx: +If you haven't contributed before, review the following items: -.. toctree:: - :maxdepth: 1 - - writing-guide - structure-formatting +* 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. How to contribute ================= diff --git a/source/clear-linux/reference/collaboration/structure-formatting.rst b/source/clear-linux/reference/collaboration/structure-formatting.rst index 60148cf2..1b8a0d5b 100644 --- a/source/clear-linux/reference/collaboration/structure-formatting.rst +++ b/source/clear-linux/reference/collaboration/structure-formatting.rst @@ -4,30 +4,32 @@ Structure and formatting ######################## Content should be organized to support scanning. Consistent organization, -formatting, and writing style helps readers quickly find what they need and -to understand the content more effectively. - -Use the organization and formatting guidelines described in this document with -the 'writing-guide'_ to create scannable content. +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. + + Markup ****** -Documentation is written using the reStructuredText markup language, -with extensive use of Sphinx roles and directives. We use Sphinx to generate -the final documentation. You can read more about reStructuredText and Sphinx -on their respective websites: +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 documentation`_ * `reStructuredText Primer`_ -You can view the content directly in the .rst markup files, or install and run -the documentation locally, in order to generate the HTML content. To run the -documentation locally, follow the instructions found in the `documentation repository`_ -README. +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 ========= @@ -51,8 +53,8 @@ For example, the "Documentation contribution guidelines" page toctree looks like writing-guide structure-formatting -Additionally, each page should include a uniquely named reST label directly -before the page title, to enable the use of 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``: @@ -86,8 +88,8 @@ Page structure Each page in the documentation should follow the basic format of: -* Overview: 1-2 sentences describing what this page will show and why it matters -* Prerequisites: Describe any pre work necessary to the content (if appropriate) +* Overview: 1-2 sentences describing what this page shows and why it matters +* Prerequisites: Describe any pre-work necessary to the content (if appropriate) * Content * Next steps: List links to next steps (if appropriate) * Related topics: List links to related content (if appropriate) @@ -98,9 +100,9 @@ Headings Use headings to section and organize your content for better readability and clarity. -* All files must have a top level heading, which will be the title for the page. +* All files must have a top level heading, which is the title for the page. * Headings should be short and descriptive. -* Headings must be written in sentence case. +* 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. @@ -147,14 +149,14 @@ Inline text formatting ********************** We use the `Microsoft Writing Style Guide`_ as our starting point for text -formatting, and execute the formatting using reST and Sphinx markup. +formatting. We execute the formatting using reST and Sphinx markup. Use our quick reference for the most commonly used inline text elements: +--------------------------------+---------------------------------------+-----------------------------+ | **Element** | **Convention** | **reST/Sphinx** | +--------------------------------+---------------------------------------+-----------------------------+ -| Emphasis | Italic. | ``*strong*`` | +| Emphasis | Italic | ``*strong*`` | +--------------------------------+---------------------------------------+-----------------------------+ | Tool names | Correctly capitalized, no quotes, | | | | bold, or italics as the basic rule. | | @@ -163,13 +165,13 @@ Use our quick reference for the most commonly used inline text elements: | | name is the command, treat it like | | | | a command. | | | | | | -| | If the tool name is lower case and | | +| | If the tool name is lowercase and | | | | used at the start of a sentence, use | | | | bold. | | +--------------------------------+---------------------------------------+-----------------------------+ -| Commands | Bold. | Use the ``:command:`` role | +| Commands | Bold | Use the ``:command:`` role. | +--------------------------------+---------------------------------------+-----------------------------+ -| Command flags | Bold. | Use the ``:command:`` role | +| Command flags | Bold | Use the ``:command:`` role. | +--------------------------------+---------------------------------------+-----------------------------+ | New terms | Italic for first use, normal for all | ``*term*`` | | | subsequent use. | | @@ -177,11 +179,11 @@ Use our quick reference for the most commonly used inline text elements: | | If it is used outside of the source | | | | of definition, link the term. | | +--------------------------------+---------------------------------------+-----------------------------+ -| Bundle names | Bold. | Use the ``:command:`` role | +| Bundle names | Bold | Use the ``:command:`` role. | +--------------------------------+---------------------------------------+-----------------------------+ -| File names, directories, paths | Title style capitalization | Use the ``:file:`` role | +| File names, directories, paths | Title style capitalization | Use the ``:file:`` role. | +--------------------------------+---------------------------------------+-----------------------------+ -| File extensions | lowercase | | +| File extensions | Lowercase | | +--------------------------------+---------------------------------------+-----------------------------+ | Example URLs (not linked) | Plain text | | +--------------------------------+---------------------------------------+-----------------------------+ @@ -198,7 +200,7 @@ Use our quick reference for the most commonly used inline text elements: +--------------------------------+---------------------------------------+-----------------------------+ | Acronyms | Spell out first use, with | Use ``:abbr:`` | | | acronym in parenthesis. | | -| | For all subsequent use, | | +| | For all subsequent uses, | | | | use the acronym. | | +--------------------------------+---------------------------------------+-----------------------------+ | Keystrokes | | Use ``:kbd:`` | @@ -212,7 +214,7 @@ Use our quick reference for the most commonly used inline text elements: | Local navigation | | ``.. contents:: :local:`` | | | | with a depth of 1 | +--------------------------------+---------------------------------------+-----------------------------+ -| Environment variables | Use the casing of the | Use ``:envvar:`` | +| Environment variables | Use the case format of the | Use ``:envvar:`` | | | environment variable. | | +--------------------------------+---------------------------------------+-----------------------------+ | Inline comments | | Use ``..`` | @@ -222,7 +224,7 @@ Use our quick reference for the most commonly used inline text elements: | parts | e.g. . | | | | | | | | Use square brackets for optional | | -| | parts | | +| | parts, | | | | e.g. [--build]. | | +--------------------------------+---------------------------------------+-----------------------------+ @@ -253,12 +255,11 @@ Lists and instructions ********************** Use a numbered list when the order or priority of the items is important, such -as when writing instructions. +as step-by-step instructions. Use a bulleted list when the order of the items is not important. -For both kinds of list, strive to keep all items in the list parallel. -Use sentence style, making all the list items sentences. See :ref:`parallelism`. +For both list types, keep all items in the list parallel. See :ref:`parallelism`. Use standard `reST list markup`_. @@ -270,14 +271,14 @@ 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 - colon. Example: "To configure the unit, do the following: " + colon. Example: "To configure the unit, perform the following steps:" * Each item in the list should be parallel. * Treat numbered list items as full sentences with correct ending punctuation. * You may interrupt numbered lists with other content, if relevant, e.g. explanatory text, commands, or code. -* Second-level steps are acceptable; Avoid third-level steps. -* Avoid single-step procedures; The minimum number of steps in a procedure +* Second-level steps are acceptable; avoid third-level steps. +* Avoid single-step procedures; the minimum number of steps in a procedure is two. * Do not create numbered lists that emulate flowcharts. The reader should be able to execute the list of steps from first to last without branching or @@ -292,12 +293,12 @@ Use bulleted lists to reduce wordiness and paragraph density, especially when a sequence is not required. Here are some guidelines for bulleted lists: * Introduce a bulleted list with a sentence. End the setup text with a - colon. Example: "To repair the unit, you will need the following: " + colon. Example: "To repair the unit, you will need the following items:" * Each item in the list should be parallel. * Avoid interrupting bulleted lists with other paragraph styles. * Second-level bullets are acceptable; avoid third-level bullets. -If using sentence style bullet lists, use correct ending punctuation. For +Use the correct ending punctuation for sentence style bullet lists. For example: **Incorrect** @@ -316,8 +317,7 @@ example: * 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. + * Do not disclose the user code to anyone, including the security company. Instructions ============ @@ -396,21 +396,29 @@ Links Use the standard `reST markup for links`_. -External links use named reference in the text, referring to a defined link/label +To add a link 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. -For example, a link is defined at the bottom of the page: +For example, a link is defined at the bottom of the page like this: .. code-block:: rest .. _wiki about dogs: https://en.wikipedia.org/wiki/Dog -And used in the content: +The same link is used in the content like this: .. code-block:: rest Check out the great `wiki about dogs`_. + + Images ****** @@ -420,8 +428,8 @@ explain a topic or example. Follow these guidelines when using graphics in support of your documentation: -* Keep it simple. Only use images that serve a specific purpose in your document, - and the image should contain only the information the reader needs. +* Keep it simple. Use images that serve a specific purpose in your document, + and contain only the information the reader needs. * Avoid graphics that will need frequent updating. Don't include information in a graphic that might change with each release, such as product versions. diff --git a/source/clear-linux/reference/collaboration/writing-guide.rst b/source/clear-linux/reference/collaboration/writing-guide.rst index 4523987c..3f9a03f1 100644 --- a/source/clear-linux/reference/collaboration/writing-guide.rst +++ b/source/clear-linux/reference/collaboration/writing-guide.rst @@ -7,16 +7,24 @@ 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: + + .. contents:: :local: :depth: 1 + + Use simple English ****************** -Write using simple English: Be brief, get to the point, communicate only -the information that is needed. Be friendly and informative. Emphasize -clarity and avoid unnecessarily complicated or technical terms. Make the -content accessible to non-native speakers. +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. Be brief ======== @@ -62,7 +70,7 @@ Follow our tips for making good word choices: more than in excess of if in the event of before prior to - if you want should you wish + if you want should one wish use utilize example instance =================== =================== @@ -70,9 +78,9 @@ Follow our tips for making good word choices: Avoid overuse of product name ============================= -Use product name only when necessary. Many sentences can be re-written -to not use the product name with no change in meaning. This keeps the -content concise and scannable. +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. @@ -81,7 +89,7 @@ Make content scannable ********************** Organize your content to make it scannable for the reader, which -helps them find what the need quickly, and helps them understand more +helps them find what they need quickly, and helps them understand more efficiently. * **Put the most important content first.** Make sure your introduction @@ -99,7 +107,7 @@ Link text All links in content should follow these guidelines: -* **Use descriptive link text**: Link text should describe where the +* **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. @@ -107,7 +115,7 @@ All links in content should follow these guidelines: 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 - this helps users scan the text. + 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". @@ -139,9 +147,9 @@ For example: Use present tense ================= -Use simple present tense instead of future tense for most text. Future -tense is acceptable for conditional statements, for example in a caution -or a warning. +Use simple present tense instead of future tense for most text. Search for the +words "will" or "shall" to find future tense instances. Future tense is +acceptable for conditional statements, for example, in a caution or a warning. For example: @@ -197,9 +205,9 @@ Use active voice whenever possible to show who or what is performing an action. * Active voice follows standard English word order: SUBJECT–VERB–OBJECT - (optional). + (where the OBJECT is optional). * Passive voice reverses the order and weakens the verb: OBJECT–be VERB–by - SUBJECT (optional). + SUBJECT (where the OBJECT is optional). For example: @@ -216,7 +224,7 @@ Or: Avoid long noun phrases *********************** -Noun phrases - a noun and everything that describe or modify it - can be +Noun phrases (a noun and other words that describe or modify it) can be difficult to understand. Try to limit the number of modifiers in a noun phrase to two. @@ -265,7 +273,7 @@ structures and how they can be made parallel with a little rewording. Grammar and punctuation *********************** -This section covers common grammatical topics relevant to the our +This section covers common grammatical topics relevant to our documentation. For detailed explanations of correct grammar and punctuation, use one of our :ref:`preferred references `. @@ -295,7 +303,7 @@ A few other tips when referring to menu items: :menuselection:`View --> Side Bar --> Hide Side Bar`" * Do not include more than 3 navigation steps in a menu selection. If - more than three steps are needed divide the steps using + more than three steps are needed, divide the steps using ``:guilabel:`` or ``:menuselection:``. For example: "Go to :guilabel:`File` and select @@ -305,11 +313,11 @@ Software version capitalization ------------------------------- When listing software or hardware version numbers, the word “version” or letter -v are lowercase. The v is closed with the number (no period). +"v" are lowercase. The v is closed with the number (no period). For example: -* Widget Pro v5.0 +* Widget Pro version 5.0 * Widget Master v2.1.12 Terms using a hyphen or slash @@ -326,8 +334,8 @@ For example: Contractions ============ -Avoid the use of contractions as they may not be clear to non-native -English-speaking audiences. +Avoid using contractions, such as it's, they're, and you're, because they may be +unclear to non-native English-speaking audiences. Quotation marks =============== @@ -342,8 +350,8 @@ Commas and colons ================= This section addresses common use of commas, semicolons, and colons in our -documentation. Refer to Merriam-Webster's Collegiate Dictionary or one of -our :ref:`preferred references ` for further detail. +documentation. Refer to one of our :ref:`preferred references ` +for further details. Use the serial comma -------------------- @@ -374,7 +382,7 @@ For example: * This is a capitalization example: Donuts do not cause holes. -* These is a non capitalization example: colons, semicolons, and commas. +* 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.