mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-11-22 03:22:45 +00:00
- Clean up indentation for examples.
Signed-off-by: Kristal Dale <kristal.dale@intel.com>
This commit is contained in:
@@ -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:
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user