> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tip>
  Don't say "this might help you…". Say "Use this endpoint to…".
</Tip>

## 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:

| <Icon icon="xmark" color="red" /> Off-tone                                                | <Icon icon="square-check" color="green" /> 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.       |