Builder-first. Clear by design. Serious about systems.Esta página define como a Lerian se comunica em toda a documentação. Todo guia, referência de API, tutorial e changelog segue esses princípios. Eles existem para manter nossa voz consistente, precisa e reconhecível — independentemente de quem escreve.
Assertivo
A Lerian fala com confiança. Sem rodeios, sem sugestões vagas, sem qualificadores desnecessários.
- Vai direto ao ponto.
- Explica com clareza.
- Evita excesso de contexto quando não agrega valor.
Tech-friendly
Técnico quando precisa ser, mas nunca inacessível.
- Usa termos corretos do mercado.
- Não simplifica demais conceitos técnicos.
- Não infantiliza o leitor.
- Assume que quem lê é um builder.
- Developers
- Tech leads
- Partners
- Product teams
Encorajador
A Lerian empodera quem constrói.
- Mostra possibilidades.
- Explica impacto.
- Deixa claro o porquê das decisões técnicas.
Direto
Cada frase justifica sua existência. Sem enchimento, sem floreios, sem desvios.
- Frases curtas.
- Explicações em ordem lógica.
- Nada de parágrafos excessivamente longos.
- Sem em dashes desnecessários.
Estruturado
A informação é organizada, previsível e escaneável.
- Bullet points quando ajudam.
- Tabelas para comparações e dados de referência.
- Títulos que descrevem o conteúdo, não o decoram.
- Informação mais importante primeiro.
Humilde e pragmático
A Lerian não promete milagres.
- Evita hype.
- Não usa buzzwords vazias.
- Explica limitações quando necessário.
- Foca em resolver problemas reais.
Inclusivo e consciente
- Evita termos capacitistas.
- Evita metáforas agressivas.
- Mantém linguagem profissional e respeitosa.
Tom por tipo de documento
Documentos diferentes servem leitores diferentes. O tom se adapta — a voz permanece a mesma.
| Tipo de documento | Tom | Descrição |
|---|---|---|
| Guias | Orientado a negócios, contextual | Explica o “porquê” por trás das decisões. Fornece contexto de quando e como aplicar conceitos. |
| Referência de API | Técnico, seco, preciso | Declara fatos. Descreve inputs, outputs e comportamento. Sem narrativa. |
| Tutoriais | Passo a passo, imperativo | Use passos numerados. Comece cada passo com um verbo. Mantenha as instruções curtas. |
| Changelogs | Factual | Declare o que mudou, o que afeta e que ação é necessária. Sem comentários. |
Palavras proibidas
Certas palavras diluem a precisão ou não acrescentam significado. Soam profissionais mas não comunicam nada. Substitua ou remova.
| Palavra/expressão | Por quê | Alternativa |
|---|---|---|
| leverage | Jargão corporativo vago | use |
| robust | Não descreve o que realmente faz | Descreva a capacidade específica |
| seamless | Esconde a complexidade da integração | Descreva o comportamento real da integração |
| powerful | Superlativo vazio | Descreva a capacidade específica |
| simple / easy | Subjetivo e menospreza o esforço | Remova, ou descreva os passos |
| just | Minimiza a complexidade | Remova |
| obviously | Assume conhecimento do leitor | Remova |
| please note that | Enchimento desnecessário | Declare a informação diretamente |
| in order to | Prolixo | to |
| utilize | Desnecessariamente formal | use |
| facilitate | Vago | enable, allow |
Exemplos
Compare escrita fora do tom e no tom correto:
| Fora do tom | No tom |
|---|---|
| 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. |