¡Hola a todos! Bienvenidos de nuevo a nuestra serie sobre redacción técnica. En nuestra última lección, nos enfocamos en adoptar la claridad; hoy hablemos de su prima cercana, la consistencia.
Imagina que estás leyendo el manual de usuario de un nuevo software. En la página uno, el botón que necesitas presionar se llama OK. En la página tres, se llama Confirmar. Y en la página cinco, es solo ✓. Confuso, ¿verdad? Este es un ejemplo clásico de inconsistencia, y puede causar una gran frustración a tus usuarios.
En la documentación técnica, la consistencia no se trata solo de buena gramática; se trata de previsibilidad y confianza. Cuando tu documentación es consistente, tus lectores saben qué esperar. Pueden aprender tu terminología y navegar tu contenido con confianza, sin tener que detenerse y adivinar lo que quieres decir.
Por qué la consistencia importa en la documentación
- Genera confianza: Cuando tus documentos son consistentes, hace que tu producto se vea más profesional, pulido y confiable.
- Reduce la confusión: Los usuarios no tienen que perder tiempo averiguando si diferentes términos significan lo mismo.
- Mejora la experiencia del usuario: Hace que tu documentación sea más fácil de leer y seguir, haciendo el recorrido del usuario más fluido.
- Ayuda a escanear: El formato consistente ayuda a los lectores a escanear documentos rápidamente para encontrar lo que buscan. La mayoría de las personas no leen los documentos completos de principio a fin, simplemente los escanean y buscan respuestas a sus preguntas.
Los pilares de la consistencia
Desglosemos la consistencia en 4 áreas principales en las que puedes empezar a enfocarte ahora mismo:
- Gramática y ortografía
- Terminología
- Formato
- Tono y voz
1. Gramática y ortografía
¿Puedes notar la diferencia cuando usas mal "haber" (¿o es a ver, haver?) en tu escritura? Usar la gramática y ortografía correctas no solo hace que tus documentos se vean pulidos y bien escritos, sino que también los hace más fáciles de entender y de traducir a otros idiomas. Con el creciente uso de resúmenes y agentes de IA, ¡asegurar una gramática correcta es vital para una comunicación clara y efectiva!
Los errores ortográficos pueden ser muy vergonzosos para la empresa y para ti como redactor. Así que, siempre haz una revisión ortográfica manual, incluso cuando tengas un software corrector excelente.
Consejo: Mejorar tu gramática, no solo en la documentación formal sino también en tus conversaciones diarias, correos electrónicos y mensajes de texto, es la forma más efectiva de mejorar tus habilidades de escritura.
2. Terminología
Si llamas a un botón Guardar en un lugar, llámalo Guardar en todas partes de tu documentación técnica. Crea una pequeña lista de términos clave o glosarios para tu proyecto y apégate a ellos. Esto incluye nombres de productos, nombres de funciones y términos técnicos. No tienes que crear un glosario masivo de la noche a la mañana, solo comienza con los términos más importantes y sigue agregando según sea necesario.
3. Formato
¿Cómo resaltas el código? ¿En bloques de código? ¿Una fuente diferente? Toma una decisión y mantente fiel a ella. ¿Usas negrita para los elementos de la interfaz? Es tu elección, pero sé consistente en toda tu documentación. Esto se aplica a los encabezados, viñetas, listas numeradas e incluso la forma en que usas la puntuación.
4. Tono y voz
La voz es la personalidad de tu documentación. Esto se mantiene consistente en todo tu contenido. La voz debe ser clara, directa, evitar la jerga, etc. El tono puede cambiar según el tipo de documento; por ejemplo, un tutorial puede usar un tono conversacional, mientras que una guía de resolución de problemas puede usar un tono más directo y calmado. Lee más al respecto en la Guía de Documentación para Desarrolladores de Google.
Consejo práctico: comienza una guía de estilo
La mejor forma de garantizar la consistencia es crear una guía de estilo simple aplicable a tu equipo u organización. ¿Tu empresa tiene una guía de estilo disponible públicamente? Si es así, inspírate en ella o puedes usar muchas de las guías de estilo disponibles en línea también.
Debes documentar los matices específicos de la empresa o el equipo en tu guía de estilo. Esto no tiene que ser un documento de 100 páginas. Puede ser un simple documento compartido o una página de Notion que enumere tus términos clave, reglas de formato y tono preferido.
Por ejemplo:
Consejo: ¡puedes ir un paso más allá y agregar estas reglas de estilo a tu linter si estás siguiendo un enfoque de docs-as-code para tu documentación técnica!
Al enfocarte en la claridad, estarás en el buen camino para crear documentación que no solo sea clara, sino también confiable y profesional. ¡Buena suerte con tu camino en la redacción técnica, piensa en qué elementos puedes incluir en tu guía de estilo y comienza hoy mismo!
Cuéntame en los comentarios qué otros temas relacionados con la escritura te interesa entender.