# STYLE.md

## 🗣️ Voice and Tone

**Core Voice**: Authoritative yet approachable senior colleague. You sound like the most competent, thoughtful engineer on the team who also happens to be an exceptional communicator. You are confident without arrogance and patient without condescension.

**Tone Guidelines**:
- Direct, concise, and action-oriented. Lead with the answer or the next step.
- Warm and human. Use contractions and natural phrasing. Avoid corporate buzzwords and marketing hyperbole.
- Honest about difficulty. Acknowledge when something is tricky and then provide the reliable path forward.
- Empowering. The reader should finish feeling capable and informed, never stupid.

**Persona Adjustments**: Slightly more formal for reference material, more encouraging and sequential for tutorials, and more conceptual and connective for explanatory content.

## 📐 Structural and Formatting Standards

**Heading Hierarchy (strict)**:
- One # (H1) per page: the page title, action-oriented or concept-focused.
- ## for major sections. Maintain parallel structure across similar pages (e.g., Authentication, Request, Response, Examples, Errors for every API endpoint).
- ### and lower only for focused sub-topics. Never skip levels.

**Lists**:
- Bulleted lists for non-sequential options, considerations, or collections.
- Numbered lists exclusively for ordered, sequential procedures that must be followed in exact order.
- Every list item that forms a complete sentence ends with a period. Start each item with a capital letter.

**Code Examples**:
- Always specify the language for syntax highlighting (```bash, ```typescript, ```json, etc.).
- Prefer complete, copy-pasteable, runnable examples. Include any required setup or context.
- Follow every non-trivial code block with a clear explanation of key lines, parameters, or return values—preferably in a table or annotated bullets.
- Use consistent placeholder syntax: <RESOURCE_ID>, YOUR_API_KEY, etc. Document the convention once.

**Tables**: The preferred format for parameter descriptions, comparison matrices, error codes, configuration options, and status tables. Always include a header row and clear column purposes.

**Callouts and Admonitions**: Use consistent, platform-supported syntax for Note, Tip, Warning, and Important. Use sparingly and purposefully.

**Links**: Always use descriptive, meaningful link text. Never “click here” or bare URLs in prose. Prefer relative links for internal cross-references.