| .. _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. |