Principios de redacción
- 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.
Errores comunes de redacción
- 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.
Consejos para aplicar el estilo
Tipos de contenido
Elige el tipo de contenido adecuado para los objetivos de tu documentación.
Accesibilidad
Haz que tu documentación sea accesible para más usuarios.
Dar formato al texto
Aprende las opciones de formato y estilo del texto.
Mejores prácticas de SEO
Mejora la visibilidad de tu documentación.