home / skills / lerianstudio / ring / voice-and-tone
This skill enforces clear, confident voice and human tone in technical docs to help readers understand complex concepts quickly.
npx playbooks add skill lerianstudio/ring --skill voice-and-toneReview the files below or copy the command above to add this skill to your agents.
---
name: ring:voice-and-tone
description: |
Voice and tone guidelines for technical documentation. Ensures consistent,
clear, and human writing across all documentation.
trigger: |
- Need to check voice and tone compliance
- Writing new documentation
- Reviewing existing documentation for style
skip_when: |
- Only checking structure → use documentation-structure
- Only checking technical accuracy → use docs-reviewer agent
related:
complementary: [writing-functional-docs, writing-api-docs, documentation-review]
---
# Voice and Tone Guidelines
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.
> ✅ Midaz uses a microservices architecture, which allows each component to be self-sufficient and easily scalable.
>
> ❌ Midaz 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 Midaz 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 (Midaz, Console, Reporter, Matcher, Flowker)
**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
This skill provides voice and tone guidelines tailored for technical documentation, ensuring content is consistent, clear, and human. It helps writers produce documentation that reads like a knowledgeable colleague guiding a developer. The guidance covers tone principles, mechanics, capitalization, terminology, emphasis, and a practical quality checklist.
The skill inspects documentation drafts against core tone principles: assertive but not arrogant, encouraging, tech-savvy yet human, and humble. It enforces writing mechanics such as second person, present tense, active voice, short sentences, and sentence-case headings. It also checks capitalization rules for product and entity names, appropriate use of contractions, emphasis and code formatting, and inclusion of the provided quality checklist.
Who is the target reader for these guidelines?
A technical reader who knows engineering concepts but is new to this system and values efficient explanations.
Should I always use contractions in docs?
Use contractions naturally to keep tone conversational, but avoid them where formality or clarity requires full forms.