La documentación desactualizada es peor que no tener documentación

Un equipo sin documentación sabe que no tiene documentación. Los ingenieros hacen preguntas, interrumpen a sus compañeros y reconstruyen el contexto verbalmente. Es ineficiente, pero al menos todos conocen la situación.

Un equipo con documentación obsoleta se enfrenta a un problema diferente. Los documentos existen, parecen fidedignos y son incorrectos. Un ingeniero sigue la guía de configuración y pierde una tarde porque la guía hace referencia a una dependencia que fue reemplazada hace tres meses. Otro ingeniero lee la descripción general de la arquitectura, toma una decisión de diseño basada en ella y descubre durante la revisión del código que la descripción general describe un sistema que fue reestructurado en el último trimestre.

Después de dos o tres experiencias de este tipo, el ingeniero deja de confiar en los documentos. Vuelven a preguntar directamente a la gente, que es lo que habrían hecho si no existiera documentación. Pero ahora el equipo está pagando el coste de mantener una documentación que nadie lee, además del coste de la transferencia de conocimiento verbal que se suponía que la documentación debía eliminar.

Este es el paradox de la documentación en su forma más dañina: la inversión en documentación ha producido rendimientos negativos porque los documentos desorientan activamente en lugar de simplemente no existir.

Cómo se queda obsoleta la documentación

La documentación no se echa a perder porque los ingenieros sean descuidados. Se echa a perder porque cada PR fusionada hace que los documentos existentes sean un poco menos precisos, y el trabajo de corrección nunca tiene prioridad.

Una refactorización cambia la forma en que se comunican dos servicios. El ingeniero actualiza el código, escribe pruebas, hace que se revise y se fusione la PR. Actualizar las tres páginas de la wiki que describen el antiguo patrón de comunicación no forma parte de la lista de verificación de la PR y no forma parte del sprint. Nadie lo asigna porque nadie está haciendo un seguimiento de qué documentos se ven afectados por qué cambios de código. Las páginas de la wiki se quedan ahí, describiendo un sistema que ya no existe, esperando a que alguien las siga y falle.

La velocidad a la que se queda obsoleta se correlaciona directamente con la velocidad de despliegue. Cuanto más rápido despliegas, más rápido se desactualiza tu documentación, lo que significa que los equipos que más necesitan documentación fiable (bases de código de rápida evolución y movimiento ágil) son aquellos cuya documentación se echa a perder más rápido.

El problema de la confianza

La confianza en la documentación, una vez perdida, es extremadamente difícil de reconstruir. Se necesitan docenas de consultas de documentos precisas y útiles para crear el hábito de consultar primero la documentación. Bastan una o dos experiencias engañosas para romperlo.

Una vez que un equipo de ingeniería ha aprendido colectivamente que no se puede confiar en los documentos, estos se vuelven invisibles. A los nuevos empleados se les dice de manera informal que la wiki está "en su mayoría obsoleta" y que deben preguntar en lugar de leer. Los documentos siguen existiendo, siguen apareciendo en los resultados de búsqueda, siguen pareciendo oficiales, pero funcionalmente han sido abandonados. Cada hora dedicada a escribirlos ha sido en vano.

La única documentación que evita este problema es la que se mantiene actualizada automáticamente. Los documentos autoescritos generados a partir de la actividad de ingeniería en vivo (PRs, hilos de Slack, grabaciones de reuniones) se actualizan a medida que cambia la actividad subyacente. Los documentos reflejan la realidad porque se escriben a partir de ella, en lugar de mantenerse al margen.

La pregunta de la auditoría

Existe una prueba sencilla para saber si tus documentos tienen este problema. Elige una página de la wiki o un documento de arquitectura al azar que se haya actualizado por última vez hace más de tres meses. Léelo. Luego, pregunta al ingeniero que actualmente es propietario de ese sistema si el documento sigue siendo preciso.

En la mayoría de los equipos, la respuesta es alguna versión de "algunas partes están bien, pero algunos detalles han cambiado". Esos detalles son los que harán perder la tarde al próximo ingeniero.

Preguntas frecuentes

¿Deberíamos simplemente eliminar los documentos obsoletos? Eliminar documentos claramente desactualizados es mejor que dejarlos para confundir a la gente. Pero la mejor solución es prevenir la obsolescencia en lugar de limpiar después de ella. Los documentos que se escriben a sí mismos a partir de fuentes en vivo no se quedan obsoletos de la misma manera porque se actualizan a medida que cambia la actividad subyacente.

¿Cómo sabemos qué documentos están obsoletos? Realiza un seguimiento de cuándo se actualizaron los documentos por última vez en relación con cuándo se modificaron por última vez los sistemas que describen. Si un documento sobre el flujo de autenticación se editó por última vez en enero y el servicio de autenticación ha tenido 40 PRs desde entonces, es casi seguro que el documento esté obsoleto.

¿Vale la pena mantener la documentación manualmente si desplegamos rápido? Cuanto más rápido despliegas, más rápido se echa a perder la documentación manual, lo que significa que el ROI de la documentación manual disminuye a medida que aumenta la velocidad de despliegue. Para equipos de ritmo rápido, la documentación automatizada es el único enfoque que mantiene el ritmo.

Lecturas relacionadas: La paradoja de la documentación, Deuda de documentación, Por qué los ingenieros odian escribir documentación. Páginas relacionadas: Documentos autoescritos, Para equipos de ingeniería.