/applying-voice-and-tone

name: ring:applying-voice-and-tone
description: "Applying the technical-writing voice and tone style guide: second person, present tense, active voice, short sentences, sentence-case headings, product/entity capitalization, contractions, and sparing emphasis. Use when checking voice/tone compliance, writing new docs, or reviewing docs for style. Skip when checking structure only (use ring:structuring-documentation) or technical accuracy only (use the docs-reviewer agent)."

Voice and Tone Guidelines

When to use

• Need to check voice and tone compliance
• Writing new documentation
• Reviewing existing documentation for style

Skip when

• Only checking structure → use ring:structuring-documentation
• Only checking technical accuracy → use docs-reviewer agent

Related

**Complementary:** ring:reviewing-docs

Write the way you work: with confidence, clarity, and care. Good documentation sounds like a knowledgeable colleague helping you solve a problem.

Core Tone Principles

Assertive, But Never Arrogant

Say what needs to be said, clearly and without overexplaining.

> ✅ Core one uses a microservices architecture, which allows each component to be self-sufficient and easily scalable. > > ❌ Core one might use what some people call a microservices architecture, which could potentially allow components to be somewhat self-sufficient.

Encouraging and Empowering

Guide users to make progress, especially when things get complex.

> ✅ This setup isn't just technically solid; it's built for real-world use. You can add new components as needed without disrupting what's already in place. > > ❌ This complex setup requires careful understanding of multiple systems before you can safely make changes.

Tech-Savvy, But Human

Talk to developers, not at them. Use technical terms when needed, but prioritize clarity.

> ✅ Each Account is linked to exactly one Asset type. > > ❌ The Account entity maintains a mandatory one-to-one cardinality with the Asset entity.

Humble and Open

Be confident in your solutions but always assume there's more to learn.

> ✅ As Core one evolves, new fields and tables may be added. > > ❌ The system is complete and requires no further development.

---

The Golden Rule

> Write like you're helping a smart colleague who just joined the team.

This colleague is: Technical and can handle complexity, new to this system, busy and appreciates efficiency, capable of learning quickly with guidance.

---

Writing Mechanics

| Rule | Use | Avoid | |------|-----|-------| | Second person | "You can create..." | "Users can create..." | | Present tense | "The system returns..." | "The system will return..." | | Active voice | "The API returns a JSON response" | "A JSON response is returned by the API" | | Short sentences | Two sentences, one idea each | One long sentence with multiple clauses |

---

Capitalization

**Sentence case for all headings** – Only capitalize first letter and proper nouns.

| ✅ Correct | ❌ Avoid | |-----------|---------| | Getting started with the API | Getting Started With The API | | Using the transaction builder | Using The Transaction Builder | | Managing account types | Managing Account Types |

Applies to: Page titles, section headings, card titles, navigation labels, table headers

---

Terminology

**Product names:** Always capitalize (Core one, Console, Reporter, Core two, Core four)

**Entity names:** Capitalize when referring to specific concept (Account, Ledger, Asset, Portfolio, Segment, Transaction, Operation, Balance)

> Each Account is linked to a single Asset.

Lowercase for general references: > You can create multiple accounts within a ledger.

---

Contractions

Use naturally to make writing conversational:

| Natural | Stiff | |---------|-------| | You'll find... | You will find... | | It's important... | It is important... | | Don't delete... | Do not delete... |

---

Emphasis

**Bold** for UI elements and key terms: Click **Create Account**, the **metadata** field

`Code formatting` for technical terms: `POST /accounts`, `allowSending`

**Don't overuse** – if everything is emphasized, nothing stands out.

---

Info Boxes

| Type | When | |------|------| | **Tip:** | Helpful information | | **Note:** | Important context | | **Warning:** | Potential issues | | **Deprecated:** | Removal notices |

---

Quality Checklist

• [ ] Uses "you" consistently (not "users")
• [ ] Uses present tense for current behavior
• [ ] Uses active voice (subject does action)
• [ ] Sentences are short (one idea each)
• [ ] Headings use sentence case
• [ ] Technical terms used appropriately
• [ ] Contractions used naturally
• [ ] Emphasis used sparingly
• [ ] Sounds like helping a colleague

---