doc/collaboration/documentation/basic.rst

.. _basic:
Basic Writing Style Guidelines
##############################

These guidelines apply to every type of document, in-code comment,
commit message or note. You can find more details of the concepts listed here in the
:ref:`detailed`.

* Limit line length to 100 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.