# Lerianstudio Ring Voice And Tone > Voice and Tone Guidelines - Skill: `tomevault-io/lerianstudio-ring-voice-and-tone` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/lerianstudio-ring-voice-and-tone` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/lerianstudio-ring-voice-and-tone/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/lerianstudio-ring-voice-and-tone --- # 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: 1. **Load this skill first** before any documentation writing 2. **Cross-reference** with `ring:writing-functional-docs` or `ring:writing-api-docs` 3. **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. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lerianstudio) — claim your Tome and manage your conversions.