doc/collaboration/documentation/about.rst

.. _about:

About the Documentation Style Guide
###################################

Purpose
*******

This style guide provides general information, guidelines, procedures, and
instructions for the documentation work of the Zephyr Project.

Consistent style is important for readers, authors and editors. For readers,
consistency promotes clarity and confidence. For example, using an
abbreviation or term consistently prevents confusion and ambiguity.
A clean and consistent style tends to give readers more confidence
in the content and the product itself.

Authors who understand the guidelines can generate consistent
content at the source, which minimizes the editor's time and
avoids mis-interpretations.

Audience
********

This style guide has two audiences:

* Primary audience: Developers who author content that describes product
  function, code examples, procedures and more. Guidelines apply to human and
  machine generated content, such as APIs.

* Technical writers that wish to create technical documentation for the
  Zephyr 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 in this document; it is available to them as a
   reference.

Methodology
***********

The :ref:`documentation` 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:`documentation` 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:devel@lists.zephyrproject.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:`documentation` 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.