mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
bced9bd6c4
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
62 lines
3.1 KiB
Plaintext
62 lines
3.1 KiB
Plaintext
---
|
|
title: "Estilo y tono"
|
|
description: "Escribe documentación técnica eficaz con un estilo coherente."
|
|
keywords: ["principios de redacción", "voz activa", "redacción técnica", "guías de estilo"]
|
|
---
|
|
|
|
<Tip>
|
|
Esta página explica las decisiones de estilo, los errores comunes y las Sugerencias de implementación para redactar documentación técnica.
|
|
</Tip>
|
|
|
|
<div id="writing-principles">
|
|
## Principios de redacción
|
|
</div>
|
|
|
|
* **Sé conciso.** Las personas leen la documentación para lograr un objetivo. Ve al grano.
|
|
* **Prioriza la claridad sobre el ingenio.** Sé simple, directo y evita la jerga o las oraciones complejas.
|
|
* **Usa voz activa.** En lugar de decir “Se debería crear un archivo de configuración”, usa “Crea un archivo de configuración”.
|
|
* **Haz que se pueda escanear.** Usa encabezados para orientar a quienes leen. Divide los párrafos densos. Usa viñetas y listas para facilitar la lectura rápida.
|
|
* **Escribe en segunda persona.** Referirte a la persona lectora facilita seguir las instrucciones y hace que la documentación se sienta más cercana.
|
|
|
|
<div id="common-writing-mistakes">
|
|
## Errores comunes de redacción
|
|
</div>
|
|
|
|
- **Errores ortográficos y gramaticales.** Incluso unos pocos errores ortográficos y gramaticales en tu documentación la hacen menos creíble y más difícil de leer.
|
|
- **Terminología inconsistente.** Llamar algo “API key” en un párrafo y luego “token de API” en el siguiente dificulta que los usuarios puedan seguir la explicación.
|
|
- **Terminología centrada en el producto.** Tus usuarios no tienen todo el contexto de tu producto. Usa un lenguaje con el que tus usuarios estén familiarizados.
|
|
- **Expresiones coloquiales.** Especialmente en localización, las expresiones coloquiales perjudican la claridad.
|
|
|
|
<div id="tips-for-enforcing-style">
|
|
## Consejos para aplicar el estilo
|
|
</div>
|
|
|
|
Aprovecha guías de estilo existentes para estandarizar tu documentación:
|
|
|
|
* [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
|
|
* [Splunk Style Guide](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse)
|
|
* [Google Developer Documentation Style Guide](https://developers.google.com/style)
|
|
|
|
Cuando tengas claros los principios de redacción que quieres implementar, automatiza todo lo que puedas. Puedes usar [verificaciones de CI](/es/deploy/ci) o linters como [Vale](https://vale.sh).
|
|
|
|
<div id="related-pages">
|
|
## Páginas relacionadas
|
|
</div>
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Tipos de contenido" icon="folder-tree" href="/es/guides/content-types">
|
|
Elige el tipo de contenido adecuado para los objetivos de tu documentación.
|
|
</Card>
|
|
|
|
<Card title="Accesibilidad" icon="person-standing" href="/es/guides/accessibility">
|
|
Haz que tu documentación sea accesible para más usuarios.
|
|
</Card>
|
|
|
|
<Card title="Dar formato al texto" icon="case-sensitive" href="/es/create/text">
|
|
Aprende las opciones de formato y estilo del texto.
|
|
</Card>
|
|
|
|
<Card title="Mejores prácticas de SEO" icon="search" href="/es/guides/seo">
|
|
Mejora la visibilidad de tu documentación.
|
|
</Card>
|
|
</CardGroup> |