75 lines
2.3 KiB
ReStructuredText
75 lines
2.3 KiB
ReStructuredText
.. _basic_writing:
|
|
|
|
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. |