86 lines
2.9 KiB
ReStructuredText
86 lines
2.9 KiB
ReStructuredText
.. _about_docs_style:
|
|
|
|
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: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:`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. |