yii2/docs/documentation_style_guide.md

Yii Documentation Style Guide

Guidelines to go by when writing or editing any Yii documentation.

This needs to be expanded.

General Style

• Try to use an active voice.
• Use short, declarative sentences.
• Demonstrate ideas using code as much as possible.
• Never use "we". It's the Yii development team or the Yii core team. Better yet to put things in terms of the framework or the guide.
• Use the Oxford comma (e.g., "this, that, and the other" not "this, that and the other").
• Numeric lists should be complete sentences that end with periods (or other punctuation).
• Bullet lists should be fragments that don't end with periods.

Formatting

Blocks

Blocks use the Markdown > Type: . There are four block types:

• Warning, for bad security things and other problems
• Note, to emphasize key concepts, things to avoid
• Info, general information (an aside); not as strong as a "Note"
• Tip, pro tips, extras, can be useful but may not be needed by everyone all the time

References

• Yii 2.0 or Yii 2 (not Yii2 or Yii2.0)
• Each "page" of the guide is referred to as a "section".

Capitalizations

• Web, not web
• the guide or this guide, not the Guide