Philosophy of this style guide

This document discusses some of the principles and philosophy behind this style guide.

Intended purpose

This style guide codifies and records our style decisions and describes our house style. The guide doesn't claim to be objectively correct.

This guide is not intended to do the following:

  • Provide an industry documentation standard.
  • Compete with other well-known style guides.
  • Replace another style guide that you already follow.
  • Provide a complete set of basic writing guidelines.
  • Provide legal advice. For legal advice, consult a lawyer.

Explanation of reasons for guidelines

We generally don't explain the reasoning behind most of our guidelines. We have a couple of reasons for that:

  • Many of our decisions are driven by accessibility, localization, globalization, and ease of understanding. Giving those reasons as explanations everywhere they apply would be repetitive.
  • Often, a given guideline is one good option among several; in those cases, we sometimes just chose one option for consistency.
  • Too much explanation can clutter up a page. Readers most often want a brief answer to a specific question, rather than a detailed explanation.

That said, we recognize that it's sometimes useful to know why we made a given choice, so we've started to include occasional explanations in the What's new page.