Voice Reference

Use this when live TONE.md is unavailable. If TONE.md exists, read it instead and treat it as newer.

Current voice

Write like an experienced developer explaining something useful to a peer. The voice is confident but not boastful, enthusiastic without hype, honest about the messy path, and generous with the reader's time.

Favor the current 2025 style over older posts: direct, warm, pragmatic, and a little wry.

Default structure

Most posts follow problem -> solution -> proof -> reflection:

1. Open on the problem.
2. Name the pain concretely.
3. Introduce the solution with one repo or docs link.
4. Show it working with realistic code.
5. Explain why it works or why it beats the alternative.
6. Name when to use it.
7. Give a short getting-started pointer.
8. Close with the lesson and an invitation to reply.

Use second person for product or library posts. Use first person for reflective or lessons-learned posts.

Treat this as an arc, not a template. After drafting, check paragraph shape. If several paragraphs start with a claim, explain it, and end with a neat closer, vary the structure. Combine some paragraphs, split one into a short beat, use bullets for example runs, and let concrete cases lead when they are stronger than abstraction.

Mechanics

• Use contractions.
• Address the reader as "you"; include "we" and "let's" naturally.
• Use present tense and active voice.
• Vary sentence length. Short fragments are fine when they earn their place.
• Vary paragraph length and openings too. Rhythm problems often survive word-level cleanup.
• Use rhetorical questions to pivot when useful.
• Prefer commas, periods, and colons over em dashes in new or heavily revised copy.
• Let code carry the argument; explain what changed or why the output matters.

Formatting

• Use ## for main sections and ### for steps.
• Use sentence case headings.
• Use bold lead-in bullets for benefits and use cases.
• Include front matter with title and a benefit-oriented description.
• Fence code with the correct language for Shiki.

Avoid

• "In today's fast-paced world", "leverage", "game-changing", "revolutionary", and similar filler.
• Hype in place of proof.
• Hedging until the recommendation becomes mush.
• Paragraphs longer than about four sentences.
• Same-shaped paragraphs in a row.
• Explaining what the article is about to explain.
• Stacking signature phrases.