Esta página explica decisiones de estilo, errores comunes y sugerencias prácticas para redactar documentación técnica.
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 de ortografía y gramática. Incluso unos pocos errores de ortografía y gramática en tu documentación la vuelven menos creíble y más difícil de leer.
- Terminología inconsistente. Llamar a algo “API key” en un párrafo y luego “API token” en el siguiente dificulta que los usuarios sigan el hilo.
- Terminología centrada en el producto. Tus usuarios no tienen todo el contexto de tu producto. Usa un lenguaje familiar para ellos.
- Coloquialismos. Especialmente en la localización, los coloquialismos perjudican la claridad.