diff --git a/source/clear-linux/reference/collaboration/structure-formatting.rst b/source/clear-linux/reference/collaboration/structure-formatting.rst index dedb94d9..7cd9910b 100644 --- a/source/clear-linux/reference/collaboration/structure-formatting.rst +++ b/source/clear-linux/reference/collaboration/structure-formatting.rst @@ -44,13 +44,13 @@ page toctree. For example, the :ref:`collaboration` page toctree looks like: - .. code-block:: rest +.. code-block:: rest - .. toctree:: - :maxdepth: 1 + .. toctree:: + :maxdepth: 1 - writing-guide - structure-formatting + 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. @@ -58,19 +58,19 @@ 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``: - .. code-block:: rest +.. code-block:: rest - .. _structure-formatting: + .. _structure-formatting: - Structure and formatting - ######################## + Structure and formatting + ######################## This page can then be referenced from other pages in the documentation using the `:ref:` role: - .. code-block:: rest +.. code-block:: rest - :ref:`structure-formatting` + :ref:`structure-formatting` Documentation organization ************************** @@ -305,6 +305,8 @@ Use the correct ending punctuation for sentence style bullet lists. For example: **Use this:** +:: + When setting the user code, remember: * Use a number that has a meaning for you. @@ -313,6 +315,8 @@ Use the correct ending punctuation for sentence style bullet lists. For example: **Not this:** +:: + When setting the user code remember: * make the user code easy to remember. Use a number that has a meaning for you @@ -389,9 +393,9 @@ Use the standard `reST markup for links`_. To add a cross-reference to another documentation page, use the `:ref:` role: - .. code-block:: rest +.. code-block:: rest - :ref:`structure-formatting` + :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. @@ -442,12 +446,15 @@ Follow these guidelines when using graphics in support of your documentation: Figure 1: This is the figure 1 caption. * Include at least one direct reference to an image from the main text, using - the figure number. + the figure number. For example: - For example: + **Use this:** :: - **Use this:** "Figure 1" - **Not this:** "The figure above or below" + Figure 1 + + **Not this:** :: + + The figure above or below Images should follow these naming and location conventions: diff --git a/source/clear-linux/reference/collaboration/writing-guide.rst b/source/clear-linux/reference/collaboration/writing-guide.rst index fcdac0a2..04d1fe30 100644 --- a/source/clear-linux/reference/collaboration/writing-guide.rst +++ b/source/clear-linux/reference/collaboration/writing-guide.rst @@ -113,10 +113,13 @@ All links in content should follow these guidelines: For example: - **Use this:** For more information about dogs, read the `dog wiki article`_. +**Use this:** :: - **Not this:** For more information about dogs, `click here`_. + For more information about dogs, read the `dog wiki article`_. +**Not this:** :: + + For more information about dogs, `click here`_. Use strong verbs **************** @@ -128,28 +131,31 @@ Use imperatives =============== Commands, also called imperatives, are the fastest and most direct way of giving -someone instructions. +someone instructions. For example: -For example: +**Use this:** :: - **Use this:** Send it to me. + Send it to me. - **Not this:** I would appreciate it if you would send it to me. +**Not this:** :: + + I would appreciate it if you would send it to me. Use present tense ================= 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. +acceptable for conditional statements, such as in a caution or a warning. For +example: -For example: +**Use this:** :: - **Use this:** The system operates at a nominal temperature of 180 degrees - Fahrenheit. + The system operates at a nominal temperature of 180 degrees Fahrenheit. - **Not this:** The system will operate at a nominal temperature of 180 - degrees Fahrenheit. +**Not this:** :: + + The system will operate at a nominal temperature of 180 degrees Fahrenheit. Avoid nominalizations ===================== @@ -169,26 +175,37 @@ For example: For example: - **Use this:** We discussed the matter. +**Use this:** :: - **Not this:** We had a discussion about the matter. + We discussed the matter. + +**Not this:** :: + + We had a discussion about the matter. Or: - **Use this:** IT has installed the software. +**Use this:** :: - **Not this:** IT has completed the installation of the software. + IT has installed the software. + +**Not this:** :: + + IT has completed the installation of the software. Avoid words ending in -ing ========================== -Avoid using words ending in -ing unless they are part of a technical name. +Avoid using words ending in -ing unless they are part of a technical name. For +example: -For example: +**Use this:** :: - **Use this:** There is no way to verify this. + There is no way to verify this. - **Not this:** There is no way of verifying this. +**Not this:** :: + + There is no way of verifying this. Use the active voice ==================== @@ -203,34 +220,48 @@ action. For example: - **Use this:** I made a mistake. +**Use this:** :: - **Not this:** A mistake was made. *(By whom?)* + I made a mistake. + +**Not this:** :: + + A mistake was made. *(By whom?)* Or: - **Use this:** We released version 2.0 in June. +**Use this:** :: - **Not this:** Version 2.0 was released in June. + We released version 2.0 in June. + +**Not this:** :: + + Version 2.0 was released in June. Avoid long noun phrases *********************** 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. +to two. For example: -For example: +**Use this:** :: - **Use this:** Integration policies for power management mechanisms. + Integration policies for power management mechanisms. - **Not this:** Power management mechanism integration policies. +**Not this:** :: + + Power management mechanism integration policies. Or: - **Use this:** Requirements for test desks that measure signal integrity. +**Use this:** :: - **Not this:** Signal integrity test deck requirements. + Requirements for test desks that measure signal integrity. + +**Not this:** :: + + Signal integrity test deck requirements. .. _parallelism: @@ -338,13 +369,15 @@ Use the serial comma -------------------- When writing a series of items, use the serial comma before the final *and* and -*or* to avoid confusion and ambiguity. +*or* to avoid confusion and ambiguity. For example: -For example: +**Use this:** :: - **Use this:** Mom, Dad, and I are going to the game. + Mom, Dad, and I are going to the game. - **Not this:** Mom, Dad and I are going to the game. +**Not this:** :: + + Mom, Dad and I are going to the game. .. _click here: https://en.wikipedia.org/wiki/Dog .. _dog wiki article: https://en.wikipedia.org/wiki/Dog