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.
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.
- Developers
- Tech leads
- Partners
- Product teams
Encouraging
Lerian empowers those who build.
- Shows possibilities.
- Explains impact.
- Makes the reasoning behind technical decisions clear.
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. |