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
Standards Loading (MANDATORY)
Voice and tone guidelines are foundational. When applying this skill:
- Load this skill first before any documentation writing
- Cross-reference with
ring:writing-functional-docsorring:writing-api-docs - Use with documentation-review for quality verification
HARD GATE: CANNOT write documentation without understanding voice and tone principles.
Blocker Criteria - STOP and Report
| Condition | Decision | Action |
|---|---|---|
| Target audience undefined | STOP | Report: "Need audience definition before writing" |
| Product terminology undefined | STOP | Report: "Need terminology guide for consistent naming" |
| Conflicting style guidelines | STOP | Report: "Need style guide clarification" |
| Brand voice undefined | STOP | Report: "Need brand voice parameters" |
Cannot Be Overridden
These requirements are NON-NEGOTIABLE:
- MUST use second person ("you") consistently
- MUST use present tense for current behavior
- MUST use active voice (subject performs action)
- MUST use sentence case for all headings
- CANNOT use condescending or arrogant tone
- CANNOT use passive voice for describing actions
Severity Calibration
| Severity | Criteria | Examples |
|---|---|---|
| CRITICAL | Consistently wrong voice or tone | Third person throughout, condescending language |
| HIGH | Multiple voice/tone violations | Passive voice abuse, future tense for current features |
| MEDIUM | Occasional inconsistencies | Mixed pronouns, some title case headings |
| LOW | Minor polish needed | Could flow better, minor word choices |
Pressure Resistance
| User Says | Your Response |
|---|---|
| "Formal writing is more professional" | "Professional ≠ formal. Clear, direct language IS professional. I'll write like a knowledgeable colleague helping." |
| "Use 'users' to sound objective" | "MUST use 'you' for direct address. 'Users' creates distance. I'll address the reader directly." |
| "Future tense sounds more polished" | "MUST use present tense for current behavior. 'Returns' not 'will return'. I'll use present tense." |
| "Title Case Looks Better" | "Sentence case is the standard. Only first word and proper nouns capitalized. I'll use sentence case." |
| "Add more emphasis, it's important" | "Over-emphasis = no emphasis. I'll use bold/caps sparingly for truly critical items." |
Anti-Rationalization Table
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "Users' is more formal/professional" | Formality ≠ quality. Direct address improves comprehension | MUST use 'you' consistently |
| "Passive voice sounds more technical" | Passive voice obscures who does what | MUST use active voice |
| "Title Case is industry standard" | It's not. Sentence case is clearer and more readable | MUST use sentence case |
| "This content is different, rules don't apply" | Voice/tone applies to ALL documentation | Apply guidelines uniformly |
| "Users will understand either way" | Consistency reduces cognitive load | MUST follow guidelines exactly |
| "The content matters more than the style" | Style IS content. Poor style obscures meaning | Voice and tone are REQUIRED |
When This Skill is Not Needed
Signs that documentation already follows voice and tone guidelines:
- Consistently uses "you" (not "users", "one", "they")
- Uses present tense for current behavior throughout
- Uses active voice for all actions
- All headings use sentence case (not Title Case)
- Tone is assertive but helpful (not arrogant or condescending)
- Contractions used naturally
- Emphasis used sparingly and purposefully
If all above are true: Voice and tone is compliant, no changes needed.