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-docs or ring: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.