Lección 1: Tus primeros pasos hacia una escritura clara
¡Hola, ingenieros de software! Si la sola idea de escribir documentación técnica (también conocida como redacción técnica) te dan ganas de gritar al vacío, esta serie es para ti. Desgloso el proceso de escritura en artículos breves, para que se sienta menos como una tarea abrumadora y más como otro desafío interesante que conquistar.
Solo para recordarte, no estás empezando desde cero. Ya tienes muchas de las habilidades que necesitas para ser un gran redactor técnico. Son maestros de la lógica y de crear soluciones elegantes en código. Están acostumbrados a ser precisos, a desglosar problemas complejos y a explicar sistemas intrincados. ¡Eso es exactamente de lo que trata la buena redacción técnica; solo que con palabras en lugar de punto y coma!
Tu primera misión: adopta la claridad
La claridad es la base de una buena redacción técnica. Tu objetivo es este: cualquiera que lea tu documentación debe entender exactamente de qué estás hablando, sin ninguna confusión. Ya sea un compañero de equipo, un nuevo desarrollador que se une al proyecto, o un usuario final; ¡enfócate en hacer que el documento sea comprensible para ellos!
Para hacer tus documentos técnicos más claros, aquí hay 5 puntos simples en los que puedes enfocarte:
1. Conoce a tu audiencia (¡incluso si eres tú mismo en el futuro!): ¿Para quién estás escribiendo? ¿Cuál es su nivel de comprensión técnica? Tenlos en cuenta al elegir tus palabras y explicar conceptos. Un buen truco es que la mayoría de los documentos técnicos para el usuario final asumen que el nivel de lectura del usuario está entre 8vo y 10mo grado. ¡Esto significa que un estudiante promedio de octavo grado puede entender tu material! Si es material altamente técnico, el nivel puede ser más alto, entre 10mo y 12vo grado. Usa verificadores de legibilidad, como Hemingway, para ver el nivel de grado.
2. KISS (¡mantenlo simple y directo!): Evita la jerga y las oraciones demasiado complejas. Imagina que se lo estás explicando a alguien inteligente pero que quizás no tenga tiempo de leer el documento varias veces. Esto es especialmente cierto cuando tu audiencia es un usuario final y no está familiarizado con tu industria o tecnología.
3. Una idea por oración: Las oraciones cortas y enfocadas son más fáciles de entender. Cuando divides información compleja en fragmentos más pequeños y manejables. Una regla general es que si una oración se vuelve más larga de 1.5 líneas en tu página (en MS Word o Google Docs), reescríbela como dos oraciones.
4. La estructura es tu amiga: Usa encabezados, subtítulos, viñetas y listas numeradas para organizar tu información de forma lógica. Esto facilita que los lectores escaneen y encuentren lo que necesitan. Piensa en ello como dividir la información en fragmentos más pequeños y legibles, en lugar de una sola página grande de texto que obliga al lector a usar más de sus habilidades cognitivas para entender el texto que tiene delante.
5. Usa la voz activa: La voz activa hace que tu escritura sea más directa y fácil de seguir. En lugar de decir "El programa fue implementado", usa "Implementamos el programa".
¡Eso es todo por nuestro primer paso! Estas son ideas simples que cualquiera podría implementar. Solo comienza enfocándote en hacer tus explicaciones lo más claras y directas posible. Pruébalo con tus tareas de documentación esta semana.
¡Sigue con esta serie y verás que documentar tu excelente trabajo no tiene por qué ser intimidante. De hecho, puede incluso ser gratificante! En la próxima entrega, profundizaremos en otro aspecto clave de la redacción técnica: pensar en la documentación como una forma de comunicación.