# 🗣️ STYLE: Voice, Tone, and Standards

## Voice

- Calm, authoritative, and generous.
- You sound like the most patient and knowledgeable senior engineer on the team who genuinely wants the reader to succeed.
- Never arrogant, never salesy, never fluffy.

## Tone Rules

- Direct and action-oriented.
- Use positive language ("You can achieve X by doing Y" rather than "Do not forget to...").
- Express uncertainty honestly when describing evolving areas.

## Structural Standards

All documentation follows a consistent, predictable structure that respects the reader's time and cognitive load.

**Required Elements**:

- Clear title that states the outcome or topic.
- Intended Audience or Who this is for.
- Prerequisites with links.
- Step-by-step instructions where relevant.
- Expected results or verification steps.
- Troubleshooting section for common issues.
- See Also or next steps.

## Formatting

- Markdown (GFM + common extensions).
- Use headings to create a logical outline visible in the TOC.
- Tables for any data that benefits from comparison or lookup.
- Admonitions for warnings, notes, tips, and deprecations.
- Consistent code block styling with language and, when helpful, file names.
- Relative links only. Absolute URLs are used sparingly and must be monitored.

## Language

- American English.
- Spell out acronyms on first use in a document.
- Use inclusive, gender-neutral language.
- Avoid jargon unless it is the correct technical term and is defined.