Por qué la documentación técnica importa más de lo que los ingenieros creen

La mayoría de los equipos de ingeniería tienen una relación complicada con la documentación. Todo el mundo coincide en que es importante. Casi nadie la prioriza. El backlog de funciones por entregar siempre parece más urgente que el de decisiones por documentar, y el resultado es una base de código que crece de forma constante mientras que la comprensión de por qué se construyó de esa manera se erosiona con la misma constancia.

Esto no es pereza. Es una respuesta racional a estructuras de incentivos que premian la entrega de código y no premian escribir sobre él. Pero los costes derivados de una documentación deficiente son reales, medibles y mucho mayores de lo que la mayoría de los equipos cree, y se acumulan de formas que se vuelven más difíciles de abordar cuanto más tiempo se ignoran.

Las cuatro funciones de la documentación

La documentación de ingeniería cumple cuatro funciones distintas, y la mayoría de los equipos solo piensa en una de ellas.

Reducir errores. Cuando se documenta el razonamiento que hay detrás de una decisión de arquitectura, los ingenieros que tocan ese sistema más adelante entienden por qué se construyó como se construyó y qué limitaciones deben respetar. Sin ese contexto, realizan cambios que parecen razonables de forma aislada pero que rompen las premisas en las que confiaba el autor original. El resultado son errores difíciles de diagnosticar porque el fallo es conceptual, no sintáctico. El código se ejecuta bien. Simplemente hace lo incorrecto.

La documentación de decisiones, el registro de por qué se eligió un enfoque particular y qué alternativas se consideraron, es la capa que les falta a la mayoría de los equipos. Los comentarios de código explican lo que hace el código. Los documentos de decisiones explican por qué existe de esta forma y no de otra. Sin el porqué, cada decisión arquitectónica es cuestionada por cada nuevo ingeniero que se topa con ella.

Acelerar la incorporación. Un nuevo ingeniero que se incorpora a un equipo bien documentado puede orientarse leyendo. Puede entender la arquitectura del sistema, las decisiones clave, las convenciones y el estado actual de los proyectos activos antes de escribir una sola línea de código. Un nuevo ingeniero que se une a un equipo mal documentado tiene que reconstruir todo esto mediante conversaciones, lo que significa interrumpir a las personas que se supone que deberían estar entregando código.

La diferencia en el tiempo de adaptación suele ser de semanas, no de días, y el coste de esas semanas se mide tanto en el salario improductivo de la nueva contratación como en la productividad interrumpida de los ingenieros más experimentados.

Preservar el conocimiento institucional. La gente se va. Cambian de equipo, cambian de empresa, se van de baja por paternidad/maternidad, son ascendidos a puestos donde ya no tocan el código. Cada salida se lleva consigo conocimiento, y el conocimiento que se va suele ser el de más valor: el contexto, el razonamiento, la historia de por qué las cosas son como son.

La documentación es el mecanismo que convierte el conocimiento personal en conocimiento organizacional, lo que significa que la organización conserva lo aprendido incluso cuando las personas que lo aprendieron se marchan. Sin documentación, la organización está constantemente volviendo a aprender cosas que ya sabía, lo que constituye una de las formas de desperdicio más costosas en ingeniería.

Habilitar herramientas de IA. Esta es la función que ha surgido más recientemente y que puede convertirse en la más importante. Cada herramienta de IA en su flujo de trabajo de ingeniería, desde asistentes de código hasta agentes internos o sistemas de documentación autoescrita, funciona mejor con más contexto. Si el conocimiento de su ingeniería reside en hilos de Slack y en las cabezas de la gente, sus herramientas de IA no pueden acceder a él. La documentación es lo que hace que la IA sea útil en su contexto organizacional específico en lugar de ser simplemente capaz de forma genérica.

Por qué la documentación sigue perdiendo frente a las funciones

Comprender por qué la documentación es importante no explica por qué se sigue dejando de hacer. La respuesta es estructural más que cultural.

La documentación genera un valor difuso a largo plazo (menos errores el próximo trimestre, incorporación más rápida de la próxima contratación, conocimiento preservado en la próxima salida) mientras que la entrega de funciones genera un valor concentrado e inmediato (solicitud del cliente cumplida, ingresos desbloqueados, parte interesada satisfecha). En cualquier marco de priorización que pondere la urgencia y la visibilidad, las funciones ganarán siempre, porque el coste de la falta de documentación es invisible hasta que causa un problema específico y rastreable, lo cual ocurre meses después de haber tomado la decisión de no documentar.

Los ingenieros también saben, y con razón, que la documentación queda obsoleta. El paradoja de la documentación es que cada PR fusionado después de escribir los documentos hace que estos sean un poco menos precisos. Escribir documentos que sabes que estarán desactualizados en cuestión de semanas parece una propuesta perdedora, y para la documentación mantenida manualmente, lo es.

Por eso la respuesta al problema de la documentación es arquitectónica más que motivacional. Decirle a los ingenieros que escriban más documentos no funciona porque la estructura de incentivos está en su contra. Eliminar por completo a los ingenieros del proceso de documentación, generando y manteniendo los documentos automáticamente a partir de la actividad de ingeniería que ya se está realizando (PRs, conversaciones de Slack, reuniones, commits), cambia la economía por completo. Los documentos se mantienen actualizados porque se escriben desde la fuente en lugar de mantenerse a mano.

El coste acumulativo de saltarse la documentación

Los costes de una documentación deficiente se acumulan de la misma manera que se acumula la deuda de documentación: de forma silenciosa, acumulativa y más rápido de lo que la mayoría de los equipos espera.

En un equipo de cinco personas, todo el mundo lo sabe todo. Todo el sistema cabe en las cabezas de unas pocas personas, y el conocimiento tribal funciona porque la tribu es pequeña. Con diez personas, empiezan a aparecer lagunas. Con veinte, las lagunas están ralentizando las cosas notablemente. Con cincuenta, el cuello de botella del conocimiento tribal es uno de los principales obstáculos para la velocidad de entrega, porque cada decisión que requiere contexto necesita una reunión o un hilo de Slack para reconstruir el contexto que nunca se escribió.

Los equipos que invierten en documentación desde el principio rara vez se arrepienten. Los equipos que lo posponen hasta que el dolor se vuelve agudo descubren que el coste de documentar retroactivamente un sistema grande y complejo es mucho más alto que el coste de documentarlo a medida que se construía. Al igual que la deuda técnica, la deuda de documentación es más barata de prevenir que de solucionar.

Preguntas frecuentes

¿Qué se debería documentar primero? Las decisiones de arquitectura, los límites del sistema y las guías de incorporación. Estos tienen el mayor impacto porque abordan los problemas más costosos: errores por malinterpretar la arquitectura, incorporaciones lentas y pérdida de conocimiento cuando la gente se va.

¿Cómo logramos que los ingenieros escriban documentación? Idealmente, no lo hace. El enfoque más sostenible es una documentación que se escribe sola a partir de la actividad de ingeniería que ya se está realizando. Si eso no es posible, dedique tiempo explícitamente (sprints de documentación, días de documentación) y haga visible la calidad de la documentación en las revisiones.

¿Es suficiente la documentación del código (comentarios, archivos README)? La documentación del código explica lo que hace el código. No explica por qué se construyó de esa manera, qué alternativas se consideraron ni cómo se relacionan los diferentes sistemas entre sí. Se necesitan ambas capas, pero la capa de decisiones y arquitectura suele ser la que falta.

Lecturas relacionadas: El coste de escribir documentos de ingeniería, Deuda de documentación, Por qué los ingenieros odian escribir documentación, Explicación de los documentos autoescritos. Páginas relacionadas: Documentos autoescritos, Para equipos de ingeniería, Retención del conocimiento.