doc/documentation/writing.rst

.. _generalWriting:

General Writing Style Guidelines
################################

These guidelines apply to every type of document, in-code comment,
commit message or note. For details on any of these items, see the
cross-reference. Many of this writing guidelines stem from the concepts
of simplified English.

* Limit line length to 80 characters. This is due to the limitations
  of the review system.

* Remove trailing white space from your documents.

* Short sentences and paragraphs. Keep sentence length down to about
  20 words.

* Include only one main idea in a sentence.

* Limit the number of clauses you use to no more than two.

* Limit the number of sentences per paragraph to about six.

* Use strong verbs.

* Use action verbs.

* Avoid weak verbs like be, have, make, and do.

* Use short direct commands and avoid niceties such as the word
  "please".

* Use the present tense wherever possible and avoid past and future
  tense verbs.

* Use Active voice. Write, "Someone does something"; don't write,
  "Something is done by someone" or "Something is done."

* Use "we" for recommendations. Write "We recommend..." as opposed to
  "It is recommended...."

* Use "you" rather than "the user" in your instructions.

* Use short common English words whenever possible.

* Limit noun phrases to three terms.

* Use parallelism in headings, sentences, and lists.

* Put conditional phrases first in cautions and warnings. For example:
  "If you do X, then Y will occur."

* Limit headings to three levels. Avoid heading levels beyond H3. If
  you have fourth, fifth, or sixth level headings, rewrite the
  information in these sections as tables or create a new section for
  them.

* To reduce ambiguity, use articles such as 'a', 'an', and 'the'
  whenever possible.

* Do abbreviate codenames by using a substitution. For example:
  \|codename\| is defined in the
  :file:`forto-collab/doc/substitutions.rst` to be replaced by "Zephyr
  Operating System".

* Place figures and tables immediately after related text.

* Place code immediately after the words "for example:" in a new line.

* Use the appropriate cross-reference format to refer to figures, code
  and tables specifically: Use "Figure X," instead of "The figure above
  or below" whenever possible.

* Avoid inserting any table or figure without having at least one
  direct cross-reference to it in the body text.

Step-by-step Procedures
***********************

* Provide a sequence of numbered steps, starting with 1. Do not
  provide a paragraph of sentences.

* Describe one action per step.

* If the user needs to do the same thing for several procedures, refer
  to earlier steps rather than repeating them.

* When steps and diagrams flow down a page side-by-side, put text on
  the left and diagrams on the right.

* When steps include commands or code blocks, put the commands or code
  blocks after the step that includes them.

* If directions can appear in only one place, either text or figure,
  put them in the text; don't hide directions in diagrams.

* When a series of steps is supported by one figure, refer to the
  figure in the introductory text: "See Figure 15 and do the following:"

* When a series of steps is supported by two or more figures, avoid
  referring to a range of figures. Rather, refer to a specific figure
  in the relevant step and show the figure immediately after the
  reference. Do not say: "See figures 15 through 22 and do the
  following:"

You can find more details of the concepts listed here in the
:ref:`detailed`.