Imagina una fábrica donde todas las máquinas están perfectamente calibradas, los operarios son expertos, y sin embargo, cada vez que alguien nuevo entra a trabajar, tarda tres semanas en entender qué hace cada palanca. Nadie diría que esa fábrica es eficiente. Y sin embargo, así funciona una enorme cantidad de proyectos de software y hardware: el producto es excelente, el equipo es brillante, y el conocimiento vive únicamente dentro de las cabezas de quienes lo construyeron.
La documentación no es un anexo cosmético del desarrollo. Es una fase de producción, tan real como el testing o el control de calidad, solo que, a diferencia de esas fases, no falla de forma ruidosa. Un bug rompe la aplicación en público. La ausencia de documentación rompe en privado: en la persona que se une al equipo y tarda el doble en ser productiva, en el cliente que abandona un producto porque no entendió cómo usarlo, en el ingeniero que hereda un sistema y tiene que hacer arqueología de código para entender una decisión que se tomó hace dos años y que nadie recuerda.
El costo que nadie ve pagar
Aquí está la trampa psicológica central: quien decide no documentar experimenta el ahorro de inmediato (un sprint más rápido, una entrega más pronta), mientras que el costo lo paga otra persona, en otro momento. Es casi un problema de física social: los beneficios de documentar están distribuidos en el futuro y en terceros; los costos están concentrados en el presente y en uno mismo. Cualquier líder de iniciativa que solo mire el corto plazo va a subestimar sistemáticamente cuánto vale escribir las cosas.
Y el costo real no es pequeño. Estudios y prácticas de la industria coinciden en algo intuitivo: incorporar a una persona nueva a un equipo sin documentación adecuada puede tomar semanas en vez de días. Un soporte técnico sin documentación clara genera tickets repetidos que consumen horas de ingenieros senior en preguntas que un buen artículo habría resuelto en segundos. Y en hardware, la falta de especificaciones claras sobre por qué se tomó una decisión de diseño puede llevar a que, dos generaciones de producto después, alguien repita un error ya resuelto, simplemente porque nadie escribió por qué se había evitado esa ruta.
Lo que la documentación realmente preserva
El código, o el esquema de un circuito, te dice qué existe. Rara vez te dice por qué existe así y no de otra forma. Las alternativas que se descartaron, las restricciones que forzaron una decisión imperfecta, el contexto de negocio que ya no es válido pero que explica una rareza técnica: nada de esto queda registrado en el artefacto final. Se pierde para siempre, salvo que alguien lo haya escrito.
Esto es lo que convierte a la documentación en algo más cercano a una memoria institucional que a un simple manual. Cuando una persona clave se va (y en algún momento, siempre se va), lo que realmente se pierde no es su código, que sigue ahí. Lo que se pierde es el porqué. Y ese porqué es exactamente lo que la documentación puede salvar.
Cuando documentar es un desperdicio
Pero hay que ser honestos: no toda la documentación vale lo mismo, y tratarla como un mandamiento absoluto es tan ingenuo como ignorarla. Documentar un prototipo desechable, o un sistema que va a cambiar por completo la semana que viene, es como pintar la fachada de una casa que se va a demoler. El valor de la documentación es proporcional a la vida útil esperada de lo que documenta, y a la distancia (en tiempo, en contexto, en identidad) entre quien la escribe y quien eventualmente la leerá.
Documentación desactualizada, además, no es neutral: es peligrosa. Miente con la autoridad de lo escrito. Un lector confía en ella, actúa según ella, y descubre el error demasiado tarde. Documentar mal, o dejar que la documentación se pudra sin mantenimiento, puede ser peor que no documentar en absoluto.
Cómo decidir, aunque nunca te lo hayas planteado
Si lideras una iniciativa de software o hardware y quieres saber cuánto invertir en documentación, hazte tres preguntas, en este orden:
¿Quién va a leer esto, y podrá preguntarme directamente? Si la respuesta es “cualquiera, en cualquier momento, sin poder preguntar” (un desarrollador externo usando tu API, un usuario común de tu producto, tu propio equipo dentro de tres años), el valor de documentar sube con fuerza.
¿Esto va a durar, o es desechable? No documentes lo que vas a tirar. Documenta lo que va a sobrevivir a la persona que lo construyó.
¿Estoy documentando el qué o el porqué? El código ya explica el qué; duplicarlo en comentarios es trabajo perdido. Lo irremplazable es el porqué: las decisiones, los descartes, los trade-offs. Eso, si no lo escribes tú, no lo escribe nadie.
La documentación no es el freno de un proyecto ágil. Es su seguro de vida: invisible mientras todo va bien, y decisivo el día en que algo, o alguien, deja de estar disponible.