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.

Methodology

The Documentation Style Guide 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 Documentation Style Guide 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.

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 Documentation Style Guide 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.