Builder-first. Clear by design. Serious about systems.Esta página define cómo Lerian se comunica en toda la documentación. Cada guía, referencia de API, tutorial y changelog sigue estos principios. Existen para mantener nuestra voz consistente, precisa y reconocible — independientemente de quién escriba.
Asertivo
Lerian habla con seguridad. Sin rodeos, sin sugerencias vagas, sin calificadores innecesarios.
- Va directo al punto.
- Explica con claridad.
- Evita exceso de contexto cuando no aporta valor.
Tech-friendly
Técnico cuando necesita serlo, pero nunca inaccesible.
- Usa términos correctos de la industria.
- No simplifica en exceso los conceptos técnicos.
- No subestima al lector.
- Asume que quien lee es un builder.
- Developers
- Tech leads
- Partners
- Product teams
Alentador
Lerian empodera a quienes construyen.
- Muestra posibilidades.
- Explica el impacto.
- Deja claro el porqué de las decisiones técnicas.
Directo
Cada oración justifica su existencia. Sin relleno, sin adornos, sin desvíos.
- Frases cortas.
- Explicaciones en orden lógico.
- Nada de párrafos excesivamente largos.
- Sin em dashes innecesarios.
Estructurado
La información es organizada, predecible y escaneable.
- Bullet points cuando ayudan.
- Tablas para comparaciones y datos de referencia.
- Encabezados que describen contenido, no lo decoran.
- La información más importante primero.
Humilde y pragmático
Lerian no promete milagros.
- Evita el hype.
- No usa buzzwords vacías.
- Explica limitaciones cuando es necesario.
- Se enfoca en resolver problemas reales.
Inclusivo y consciente
- Evita términos capacitistas.
- Evita metáforas agresivas.
- Mantiene un lenguaje profesional y respetuoso.
Tono por tipo de documento
Diferentes documentos sirven a diferentes lectores. El tono se adapta — la voz permanece igual.
| Tipo de documento | Tono | Descripción |
|---|---|---|
| Guías | Orientado al negocio, contextual | Explica el “por qué” detrás de las decisiones. Proporciona contexto sobre cuándo y cómo aplicar conceptos. |
| Referencia de API | Técnico, seco, preciso | Declara hechos. Describe entradas, salidas y comportamiento. Sin narrativa. |
| Tutoriales | Paso a paso, imperativo | Usa pasos numerados. Comienza cada paso con un verbo. Mantén las instrucciones cortas. |
| Changelogs | Factual | Indica qué cambió, qué afecta y qué acción se necesita. Sin comentarios. |
Palabras prohibidas
Ciertas palabras diluyen la precisión o no aportan significado. Suenan profesionales pero no comunican nada. Reemplázalas o elimínalas.
| Palabra/frase | Por qué | Alternativa |
|---|---|---|
| leverage | Jerga corporativa vaga | use |
| robust | No describe lo que realmente hace | Describe la capacidad específica |
| seamless | Oculta la complejidad de la integración | Describe el comportamiento real de la integración |
| powerful | Superlativo vacío | Describe la capacidad específica |
| simple / easy | Subjetivo y despectivo del esfuerzo | Elimina, o describe los pasos |
| just | Minimiza la complejidad | Elimina |
| obviously | Asume conocimiento del lector | Elimina |
| please note that | Relleno innecesario | Declara la información directamente |
| in order to | Verboso | to |
| utilize | Innecesariamente formal | use |
| facilitate | Vago | enable, allow |
Ejemplos
Compara escritura fuera de tono y en tono:
| Fuera de tono | En tono |
|---|---|
| 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. |