# 🎨 Vellum Style & Voice Guide

## Core Voice Characteristics

**The Trusted Principal Writer**

- Calm, confident, and deeply knowledgeable
- Warm but never casual or slangy unless quoting
- Precise without being pedantic
- Helpful without being condescending

**Sentence Style**
- Short to medium length. One idea per sentence.
- Lead with the answer or action.
- Use "you" to address the reader directly.
- Active voice is default: "Configure the retriever..." not "The retriever is configured by the user..."

## Tone Spectrum (by Document Type)

- **Getting Started / Tutorials**: Encouraging, step-by-step, celebratory of small wins
- **Reference**: Neutral, exhaustive, scannable, formulaic
- **Explanatory / Architecture**: Thoughtful, illuminating, connecting concepts
- **Troubleshooting**: Diagnostic, empathetic, structured (symptom → cause → resolution)
- **Release Notes / Changelogs**: Factual, scannable, categorized (Features, Fixes, Deprecations, Security)

## Strict Formatting Rules

### Markdown Discipline
- H1 (`#`) is reserved exclusively for the document title. Never use more than one H1 per page.
- Use `##` for top-level sections in most documents.
- Use ordered lists for sequential steps. Use unordered for collections.
- Use definition lists (`term
: definition`) for glossaries and parameter descriptions where appropriate.

### Required Structural Elements (for most long-form docs)
Every major document MUST contain:
1. **Metadata block** (YAML frontmatter or table): Audience, Version applicability, Last reviewed, Owner
2. **Context / Why this matters** (1-2 paragraphs)
3. **Prerequisites** (clear, with links)
4. **Expected outcome** or "You will be able to..."
5. **Core content** organized by Diátaxis mode
6. **Next steps / Related reading**
7. **Feedback / Edit this page** call to action (where applicable)

### Code & Examples
- Every code block MUST declare the language: ```python, ```bash, ```json
- For API calls, show both request and a realistic response.
- Always include comments explaining non-obvious parts.
- For complex flows, provide both the "happy path" and at least one "error path" example.

### Callouts & Admonitions
Use the following consistent pattern:

> **Note**
> 
> Additional context that is helpful but not critical.

> **Warning**
> 
> Something that can cause data loss, unexpected costs, or security issues.

> **Tip**
> 
> A pro move or lesser-known technique.

> **Important**
> 
> Information the reader must internalize to succeed.

### Tables
- Always have a header row.
- Use alignment (`:---`, `:---:`, `---:`)
- For boolean or status columns, use ✅ ❌ or clear words.
- Include a "Description" column for complex parameters.

### Terminology & Language
- Never use "simple", "simply", "just", "easy", "trivial", "straightforward" to describe user actions involving your system.
- Spell out acronyms on first use: Retrieval-Augmented Generation (RAG).
- Use inclusive language. Avoid ableist terms ("crazy", "insane", "blindly").
- Prefer "deprecate" over "sunset". Use precise deprecation timelines.

## Visual & Scannability

- Use bold for key terms and UI elements on first mention.
- Use `inline code` for all technical identifiers, field names, CLI commands, and HTTP methods.
- Break long sections with horizontal rules or subheadings every 400-600 words.
- Include "Jump to" anchor links in very long reference pages.

This style builds instant trust and makes readers feel they are in the hands of professionals who respect their time.