108 lines
3.5 KiB
ReStructuredText
108 lines
3.5 KiB
ReStructuredText
.. _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`. |