Últimamente he estado revisando mucha documentación de proyectos y me he dado cuenta de un patrón que se repite bastante: la forma en la que se escribe puede hacer que algo claro se vuelva confuso, o que algo complejo sea más accesible.
No es solo cuestión de escribir bien técnicamente. Es sobre cómo nos comunicamos con quien nos va a leer, cómo facilitamos que entiendan lo que queremos transmitir.
Hablar en tercera persona o impersonal
Algo que marca diferencia es evitar escribir en primera persona. La documentación no debería estar llena de “yo hice esto” o “en mi caso prefiero aquello”. La documentación técnica busca ser objetiva, ser una fuente de información que cualquiera pueda consultar sin depender de la opinión personal del autor.
En lugar de escribir “Yo suelo usar este comando para…”, es mejor redactar “Este comando se utiliza para…” o “El comando permite…”. De esta forma, la información se presenta de manera neutral y se centra en el contenido, no en quien lo escribe.
Cuando se usa la tercera persona o una forma impersonal, la documentación se vuelve más profesional y más fácil de mantener. Si alguien más tiene que actualizarla en el futuro, no tiene que cambiar el punto de vista narrativo, simplemente añade o modifica la información necesaria.
Ser explícito y concreto
Otro punto importante es decir todo de la forma más explícita posible. Nada de asumir que el lector va a entender algo porque “es obvio” o porque “todo el mundo sabe eso”. Lo que para una persona es evidente, para otra puede ser completamente nuevo.
Cuando se documenta, hay que pensar en ser concreto. Si se habla de un archivo, mencionar exactamente cuál es, dónde está ubicado. Si se menciona un parámetro, explicar qué hace, qué valores acepta, qué pasa si no se incluye. Si se describe un proceso, detallar los pasos de forma clara y ordenada.
Es mejor pecar de dar demasiada información que dejar cabos sueltos. La ambigüedad en la documentación genera dudas, y las dudas generan pérdidas de tiempo intentando adivinar qué se quería decir realmente.
Pequeños detalles, gran impacto
Estos dos principios pueden parecer simples, pero aplicarlos de forma consistente puede cambiar completamente la calidad de la documentación. No se trata solo de escribir para que otros entiendan hoy, sino de crear documentación que siga siendo útil meses o años después, cuando nadie recuerde el contexto original.
Al final, documentar bien es un acto de empatía. Es pensar en quien va a leer eso después, en facilitarle la vida, en ahorrarle tiempo y frustración. Y eso se nota.