Stay organized with collections
Save and categorize content based on your preferences.
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-10-15 UTC."],[[["This style guide documents the preferred writing style for this organization's content, focusing on internal consistency rather than setting industry standards."],["It does not aim to be a comprehensive writing guide or replace existing style guides, primarily focusing on stylistic choices rather than basic writing principles."],["While it prioritizes conciseness over detailed explanations, the guide occasionally provides rationale for specific choices, particularly concerning accessibility and localization."],["Users are expected to act ethically and legally regarding documentation, regardless of whether they have read the guidelines."],["This guide is subject to change and doesn't limit the organization's ability to modify its documentation."]]],[]]
