| 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
