mirror of
https://github.com/zephyrproject-rtos/zephyr
synced 2025-09-06 09:01:57 +00:00
3cad1c6e6d
The style guidelines are mandatory patterns of writing designed to ease the creation of documentation for the Zephyr project. All authors, which includes the developers, must adhere to the style guide. More detailed information, including examples, will be added shortly. Change-Id: I198e5fe90b279560a60c028260b1fc8c972d322a Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
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`. |