Voice and tone

Learn how Lerian writes — assertive, tech-friendly, and clear by design — so every guide, reference, and changelog sounds consistent.

Builder-first. Clear by design. Serious about systems.

This page defines how Lerian communicates across all documentation. Every guide, API reference, tutorial, and changelog follows these principles. They exist to keep our voice consistent, precise, and recognizable — regardless of who writes.

Assertive

---

Lerian speaks with confidence. No hedging, no vague suggestions, no unnecessary qualifiers.

• Gets straight to the point.
• Explains with clarity.
• Avoids excess context when it doesn’t add value.

Don’t say “this might help you…”. Say “Use this endpoint to…”.

Tech-friendly

---

Technical when it needs to be, but never inaccessible.

• Uses correct industry terms.
• Doesn’t oversimplify technical concepts.
• Doesn’t talk down to the reader.
• Assumes the reader is a builder.

Our communication is designed for:

• Developers
• Tech leads
• Partners
• Product teams

Encouraging

---

Lerian empowers those who build.

• Shows possibilities.
• Explains impact.
• Makes the reasoning behind technical decisions clear.

Not arrogant. Collaborative.

Direct

---

Every sentence justifies its existence. No filler, no fluff, no detours.

• Short sentences.
• Explanations in logical order.
• No excessively long paragraphs.
• No unnecessary em dashes.

Structured

---

Information is organized, predictable, and scannable.

• Bullet points when they help.
• Tables for comparisons and reference data.
• Headings that describe content, not decorate it.
• Most important information first.

Humble and pragmatic

---

Lerian doesn’t promise miracles.

• Avoids hype.
• Doesn’t use empty buzzwords.
• Explains limitations when necessary.
• Focuses on solving real problems.

Inclusive and conscious

---

• Avoids ableist terms.
• Avoids aggressive metaphors.
• Maintains professional, respectful language.

Tone by document type

---

Different documents serve different readers. The tone adapts — the voice stays the same.

Document type	Tone	Description
Guides	Business-oriented, contextual	Explain the “why” behind decisions. Provide context for when and how to apply concepts.
API Reference	Technical, dry, precise	State facts. Describe inputs, outputs, and behavior. No narrative.
Tutorials	Step-by-step, imperative	Use numbered steps. Start each step with a verb. Keep instructions short.
Changelogs	Factual	State what changed, what it affects, and what action is needed. No commentary.

Banned words

---

Certain words dilute precision or add no meaning. They sound professional but communicate nothing. Replace or remove them.

Word/phrase	Why	Alternative
leverage	Vague corporate jargon	use
robust	Does not describe what it actually does	Describe the specific capability
seamless	Hides integration complexity	Describe the actual integration behavior
powerful	Empty superlative	Describe the specific capability
simple / easy	Subjective and dismissive of effort	Remove, or describe the steps
just	Minimizes complexity	Remove
obviously	Assumes reader knowledge	Remove
please note that	Unnecessary filler	State the information directly
in order to	Wordy	to
utilize	Unnecessarily formal	use
facilitate	Vague	enable, allow

Examples

---

Compare off-tone and on-tone writing:

Off-tone	On-tone
This powerful feature allows you to seamlessly integrate with our robust API.	This feature connects your service to the Midaz API through webhook events.
You might want to consider using the retry mechanism.	Use the retry mechanism to handle transient failures.
Please note that the API utilizes OAuth 2.0 in order to authenticate requests.	The API authenticates requests with OAuth 2.0.
It’s really easy to get started with Midaz — just install the SDK and you’re good to go!	Install the SDK, then follow the setup steps in the quickstart guide.