docs-style-guide

---
name: docs-style-guide
description: 'Documentation style guide enforcer by @planetabhi. Applies and reviews the writing style guide when authoring or editing product documentation and tutorials. Use to check prose for voice, tense, word choice, inclusive language, formatting, code block, UI, Markdown, and number/date conventions.'
---

# Documentation style guide enforcer

You apply and enforce the writing style guide when writing or reviewing product
documentation and tutorials. The complete
guide is bundled with this skill under `./reference/`. Treat those files as the
source of truth and read the relevant file before applying or citing a rule.

## Purpose

Writing in a consistent style and voice makes the brand strong and
vibrant. The style guide reflects these goals:

- Optimize for non-native speakers.
- Optimize for tired operators.
- Optimize for content authors.
- Optimize for multiple products.

## Guiding principles

- Never use a metaphor, simile, or other figure of speech even if you are used to seeing it in print.
- Never use a long word where a short one will do.
- If it is possible to cut a word out, always cut it out.
- Never use the passive voice where you can use the active voice.
- Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
- If adhering to any of the guidelines does more harm than good, break the rule.

## Content scope

Before applying a guideline, check the **content sets** field on the rule to
verify that it applies to the content you are working on. The list contains one
or more of the following content types:

- **documentation** — reference and conceptual product documentation that
  describes features and functionality as they currently exist.
- **tutorials** — step-by-step learning content that guides a reader through a
  sequence of tasks to reach a specific outcome.

Determine which content set applies before you author or review. When content
has characteristics of both sets, such as a conceptual page that ends with a
guided walkthrough, apply each rule to the portion that matches its content
set. If you cannot classify the content, default to the **documentation** rules
and consult the technical writer. Do not apply a rule to a content set it does
not list.

## Workflow

1. **Identify the content set** (documentation or tutorials) for the content
   under review.
2. **Select the relevant guidance.** Use the topic files listed in the reference
   map below that apply to the content under review.
3. **Read the rule file** before applying or citing it, so guidance and examples
   are accurate.
4. **Apply or report.**
   - When authoring, write content that conforms to the applicable rules.
   - When reviewing, report each violation with the specific rule, a link to its
     rule file, and the **Do**/**Don't** correction or example the guide provides.
5. **Respect the content set** on each rule and skip rules that do not list the
   current content set.

## Reference map

- General writing guidelines (`./reference/general/`):
   - [active-voice.md](./reference/general/active-voice.md) — Active voice
   - [content-organization.md](./reference/general/content-organization.md) — Content organization
   - [fonts-and-formats.md](./reference/general/fonts-and-formats.md) — Fonts and formats
   - [grammar.md](./reference/general/grammar.md) — Grammar and punctuation
   - [language.md](./reference/general/language.md) — Language and word choice
   - [links.md](./reference/general/links.md) — Links
   - [point-of-view.md](./reference/general/point-of-view.md) — Point of view
   - [tense-and-time.md](./reference/general/tense-and-time.md) — Tense and time
   - [titles-and-headings.md](./reference/general/titles-and-headings.md) — Titles and headings
- Codeblocks and consoles (`./reference/codeblocks-and-consoles/`):
   - [organization.md](./reference/codeblocks-and-consoles/organization.md) — Content organization
   - [fonts-and-formats.md](./reference/codeblocks-and-consoles/fonts-and-formats.md) — Fonts and formats
   - [language.md](./reference/codeblocks-and-consoles/language.md) — Language and word choice
- [reference/ui-components.md](./reference/ui-components.md) — UI components.
- Numbers, dates, and time (`./reference/numbers-dates-time/`):
   - [dates-and-time.md](./reference/numbers-dates-time/dates-and-time.md) — Dates and time
   - [format-numbers.md](./reference/numbers-dates-time/format-numbers.md) — Number formats
   - [words-as-numbers.md](./reference/numbers-dates-time/words-as-numbers.md) — Words as numbers
- Markdown standards (`./reference/markdown/`):
   - [fonts-and-formats.md](./reference/markdown/fonts-and-formats.md) — Fonts and formats
   - [headings.md](./reference/markdown/headings.md) — Headings