Add General documentation style guidelines.

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>

doc/documentation/documentation.rst

@@ -0,0 +1,160 @@
+.. _style:
+
+Zephyr Project Documentation Style Guide
+########################################
+
+.. _styleIntro:
+
+Introduction
+************
+This is the Zephyr Project Documentation Style Guide, a document
+produced and maintained by the |project|. This chapter provides
+overview information about the scope and purpose of this manual, along
+with related resources.
+
+Scope
+=====
+This guide addresses general documentation style and usage issues. It
+includes the following:
+
+:ref:`styleIntro`
+
+Explains the scope, purpose, methodology of the document.
+
+
+:ref:`generalWriting`
+
+Covers the basic issues of writing styles, including general writing
+guidelines and specific guidelines for step-by-step procedures.
+
+:ref:`detailed`
+
+Offers specific examples of all guidelines included in the
+:ref:`generalWriting`. Additionally, it contains the guidelines for
+module-based writing.
+
+:ref:`words`
+
+All the spelling, usage, grammar, mechanics, punctuation,
+capitalization, and various rules about writing technical documents.
+
+:ref:`ReST`
+
+Specifically addresses writing standards and syntax with regard to
+Restructuredtext.
+
+This reference manual is written in American English.
+
+Related Reference Guidelines
+
+These related guidelines include information that may prove useful to
+developers:
+
+* :ref:`Gerrit`
+* :ref:`code`
+
+This style guide applies to the following technical documents:
+
+* Commit messages.
+
+* Technical presentations.
+
+* Stand alone documents in Restructuredtext.
+
+* All in-code comments.
+
+* Release notes.
+
+
+Purpose
+=======
+This manual provides general information, guidelines, procedures, and
+instructions for the documentation work of the |project|. In addition,
+this manual includes a style guide that details document conventions.
+
+Consistent style is important for readers and writers. For readers,
+consistency promotes clarity and confidence. For example, using an
+abbreviation or term consistently prevents confusion and ambiguity. In
+addition, producing information that has a clean and consistent style
+tends to give readers more confidence in the information.
+
+For writers, consistency is part of good publishing. Generally, the
+poorer the style, the poorer the reader's opinion of the document,
+writer, and publisher.
+
+Audience
+========
+This style guide has two audiences:
+
+* Primary audience: Technical writers that wish to create technical
+  documentation for the |project| (writers).
+* Secondary audience: Developers that wish to document their code and
+  features (authors).
+
+Where the guideline makes a distinction for the two audiences, we will
+refer to these groups as writers and authors.
+
+.. note::
+	As secondary audience, developers are not expected to master the style
+   and writing guidelines int his document; it is available to them as a
+   reference.
+
+Methodology
+===========
+
+The :ref:`style` contains exceptions to the other style guides. It also
+contains additional material not found in those sources.
+
+To research a style question, look in the :ref:`style` first. If the
+question is not answered there, send your question to the
+`mailing list`_. For hyphenation, spelling, or terminology usage
+questions look in the Merriam-Webster's Collegiate Dictionary.
+
+.. _mailing list: mailto:foss-rtos-collab@lists.01.org
+
+If the question is answered in the existing style guide or dictionary,
+the solution is implemented and enforced as described.
+
+
+References
+==========
+
+In creating and refining the policies in this document, we consulted the
+following sources for guidance:
+
+* The Chicago Manual of Style (15th edition), The University of
+  Chicago Press;
+* Merriam-Webster Dictionary;
+* Microsoft Manual of Style for Technical Publications, Microsoft
+  Press;
+* Microsoft Press Computer Dictionary, Microsoft Press; and
+* Read Me First!, Oracle Technical Publications.
+
+These sources do not always concur on questions of style and usage; nor
+do we always agree with these sources. In areas where there is
+disagreement, the decisions made may be explained within the respective
+section.
+
+The :ref:`style` takes precedence over all other style guides in all
+cases. In cases where the guide does not address the issue at hand the
+issue must be reported to the `mailing list`_.
+
+Use Merriam-Webster's Collegiate Dictionary to determine correct
+spelling, hyphenation, and usage.
+
+.. _writing:
+
+Style Guidelines
+****************
+
+This section addresses writing styles. It provides a rules for writing
+clear, concise and consistent content. It is written using
+Restructuredtext and contains all the use cases for the markup.
+
+.. toctree::
+	:maxdepth: 3
+
+   writing.rst
+   detailed.rst
+   words.rst
+   rest.rst

doc/documentation/writing.rst

@@ -0,0 +1,108 @@
+.. _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`.