El Technical Design Doc que tu equipo realmente usa
Una Tech Lead acaba de asumir un equipo que mantiene el servicio de facturación de su empresa. El espacio de documentación del equipo tiene decenas de design docs. Los abre uno por uno durante su primera semana y encuentra lo mismo en todos: secciones completas, diagramas cuidados, aprobaciones firmadas y ningún comentario posterior a la fecha de aprobación. Nadie los ha vuelto a abrir. Mientras tanto, el ingeniero que diseñó la mitad de ese servicio ha anunciado que se va en unas semanas. Cuando alguien del equipo tiene una duda sobre por qué el sistema funciona como funciona, le escribe a él por chat. Nadie consulta los documentos.
Tiene que decidir qué hacer con el proceso de Technical Design Docs antes de que esa persona se vaya. El equipo desconfía de cualquier cosa que huela a burocracia. Ella tiene tiempo para cambiar una sola cosa.
Dos respuestas sensatas al mismo cementerio documental
La primera respuesta es endurecer el proceso. Si los documentos no sirven, quizá estén incompletos. Una plantilla exhaustiva, con secciones obligatorias para arquitectura, modelo de datos, APIs, seguridad, observabilidad y plan de despliegue, garantiza que nada quede fuera. Un comité de revisión asegura que la calidad sea uniforme. Will Larson describe en An Elegant Puzzle cómo las organizaciones, cuando la inconsistencia técnica se vuelve aguda, terminan recurriendo a lo mismo: un grupo centralizado y responsable, normalmente un "architecture group". Esta respuesta tiene lógica. Hay equipos donde la falta de rigor en el diseño produce sistemas que nadie entiende tres meses después.
La segunda respuesta es abandonar los documentos formales. Si nadie los lee, el esfuerzo de escribirlos se desperdicia. El código es la fuente de verdad y las conversaciones resuelven lo demás. Marty Cagan cuenta en Inspired que nunca ha visto funcionar el intento de documentar un sistema hasta capturarlo todo: los sistemas crecen más rápido de lo que cualquiera puede documentarlos. Esta respuesta también tiene lógica. Hay equipos pequeños donde un TDD formal es teatro.
Las dos fallan en el caso concreto que tiene delante. La plantilla exhaustiva produciría más documentos como los que ya nadie abre. Abandonar los documentos dejaría que el conocimiento del ingeniero que se va salga por la puerta con él. Para ver qué hacer, la Tech Lead necesita entender primero por qué los documentos actuales están muertos.
Para quién escribe quien escribe un TDD
Empieza por la pregunta más directa: ¿para quién se escribieron esos documentos?
Fíjate en el patrón que encontró. Todos tienen aprobaciones y ninguno tiene actividad posterior. El documento cumplió su función el día en que alguien lo firmó. Su lector real era el aprobador, y el aprobador tiene una pregunta muy específica: ¿este diseño es razonable? Para responderla, necesita ver que el autor pensó en las cosas que suelen salir mal. Las secciones exhaustivas sirven exactamente para eso. Demuestran diligencia.
El lector que llega meses después tiene otra pregunta. Quiere cambiar algo y necesita saber si puede hacerlo sin romper una suposición que no ve. Ese lector no necesita que alguien le demuestre diligencia. Necesita saber qué estaba pensando el diseñador.
Un documento optimizado para el aprobador no responde las preguntas del lector futuro, y por eso nadie lo vuelve a abrir.
Lo que el código nunca va a contar
La siguiente pregunta sale de la anterior: ¿qué necesita ese lector futuro que no pueda encontrar en otro sitio?
El argumento de Cagan contiene la respuesta, aunque él no la desarrolla. Concede que el código tiene la respuesta definitiva sobre el sistema, pero solo la respuesta actual. No tiene la razón detrás de las decisiones ni su historia. John Ousterhout precisa el problema en A Philosophy of Software Design. Ousterhout llama "unknown unknowns" a la situación en la que un desarrollador no sabe qué código tiene que tocar ni qué información tiene que considerar para hacer un cambio. Su observación más incómoda es que leer todo el código tampoco basta. Un cambio puede depender de una decisión de diseño sutil que nunca nadie documentó.
Piensa en lo que eso significa para el servicio de facturación. El código muestra que los reintentos de cobro esperan un intervalo concreto. No muestra que ese intervalo existe porque un proveedor de pagos penaliza los reintentos rápidos. No muestra que el equipo evaluó una cola con backoff exponencial y la descartó. Tampoco muestra qué tendría que cambiar en el mundo para que esa decisión dejara de ser válida. Ese conocimiento vive hoy en la cabeza del ingeniero que se va, y es justo lo que el equipo le pregunta por chat.
Aquí aparece el primer resultado contraintuitivo. Las secciones que la plantilla exhaustiva exige con más insistencia son las menos valiosas: arquitectura, modelo de datos, contratos de API. Describen lo que el código ya dice. Las secciones que casi ninguna plantilla exige son las únicas que el código no puede reemplazar: alternativas descartadas, restricciones asumidas y condiciones de revisión.
El documento que envejece con fecha
Si el valor está en el razonamiento, la pregunta siguiente es inevitable: ¿hay que mantener actualizado el TDD a medida que el sistema cambia?
La respuesta habitual es que sí, y es la que mata a los documentos. Un TDD que describe la estructura actual del sistema empieza a mentir en cuanto alguien hace un cambio que no actualiza el documento. El lector que encuentra una sola discrepancia deja de confiar en todo el texto. Un documento en el que nadie confía cuesta más que no tener documento, porque obliga a verificar cada afirmación contra el código.
Fíjate en lo que pasa si el documento renuncia a describir el presente. Un TDD centrado en la decisión, con fecha y congelado tras su aprobación, nunca miente. Dice lo que el equipo sabía y decidió en un momento concreto. Cuando la decisión cambia, alguien escribe otro documento que reemplaza al anterior y lo enlaza. El lector encuentra una cadena de decisiones fechadas, cada una verdadera en su contexto.
Un cuaderno de bitácora funciona igual. Nadie corrige la entrada de ayer con lo que pasó hoy. Su valor está precisamente en que registra lo que la tripulación sabía cuando decidió el rumbo. La analogía se rompe en un punto que importa: una bitácora la escribe una sola persona. Un TDD que escribe una sola persona reproduce el problema que pretende resolver.
Una plantilla que pregunta en vez de declarar
Esa ruptura lleva a la pregunta que la Tech Lead había pasado por alto: ¿quién tiene el conocimiento necesario para escribir el documento?
La respuesta fácil es "el autor del diseño". Esa respuesta es incompleta. El autor conoce su razonamiento. No conoce el modo de fallo que la persona de guardia vio el trimestre pasado. Tampoco conoce la dependencia que otro equipo construyó sobre un comportamiento no documentado, ni la restricción contractual que solo conoce alguien de finanzas. El conocimiento relevante para cualquier decisión de diseño está repartido entre personas que no saben que lo tienen hasta que alguien les hace la pregunta correcta.
Esto cambia el papel de la revisión. En el modelo del comité, un grupo central valida la calidad del diseño. Ese grupo tampoco tiene el conocimiento disperso. Tiene más autoridad, pero no más información. Larson presenta el architecture group como la herramienta a la que la gente acaba recurriendo cuando el problema se vuelve agudo, no como la primera opción. La revisión que funciona es la que convoca a quienes el cambio afecta, porque son ellos quienes saben algo que el autor no sabe.
Accelerate aporta la otra mitad del argumento. Nicole Forsgren, Jez Humble y Gene Kim encontraron que los equipos con mejores capacidades de arquitectura necesitan poca comunicación con otros equipos para entregar su trabajo. Un TDD bien construido es una de las formas en que ese desacoplamiento se vuelve posible. Funciona como una interfaz asíncrona: otro equipo puede entender una decisión sin reunirse con quien la tomó.
Con esta cadena completa, la plantilla casi se escribe sola. La cabecera lleva la fecha, el estado del documento (borrador, aprobado o reemplazado por otro, con enlace) y los nombres de quienes revisaron, no de quienes firmaron. Sigue el problema, contado en el lenguaje de quien lo sufre y no en el de la solución. Después vienen las restricciones asumidas, es decir, lo que tiene que seguir siendo cierto para que este diseño sea válido. Esta sección es la que avisa al lector futuro de cuándo puede ignorar el documento. Siguen las alternativas descartadas, cada una con la razón concreta por la que el equipo la rechazó, y la decisión tomada, en pocas líneas. Al final van las preguntas abiertas, cada una dirigida a una persona con nombre, porque una pregunta sin destinatario no tiene respuesta. Los diagramas y los contratos de API entran solo cuando hacen falta para entender la decisión, nunca para describir el sistema entero.
La plantilla de TDD que acompaña a este post, disponible para suscriptores, sigue exactamente esa estructura. Cabe en dos páginas porque todo lo que el código ya dice queda fuera.
Las semanas que le quedan al ingeniero
Ahora la Tech Lead puede volver a su decisión con criterio propio. No necesita una plantilla más exigente ni abolir los documentos. Pedirle al ingeniero que se va que documente el sistema sería repetir el error de Cagan a escala individual: no da tiempo, y el resultado describiría un presente que caducará pronto.
Lo que sí puede hacer es preguntarle al equipo qué decisiones del servicio les generan más dudas. Las respuestas ya existen en el historial del chat. Con esa lista, el ingeniero escribe TDDs retrospectivos solo para esas decisiones, con alternativas descartadas y restricciones asumidas, y los revisan las personas que hacían las preguntas. El equipo define qué conocimiento hay que rescatar. Ella diseña el formato y el momento.
Diseñar para el lector que llega sin el autor
La lección generaliza a cualquier artefacto cuyo propósito sea sacar conocimiento de la cabeza de una persona: runbooks, postmortems, guías de onboarding, registros de decisiones. Cada uno sobrevive si se escribe para quien llega cuando el autor ya no está. Tiene que limitarse a lo que la fuente primaria no puede decir, y llevar una fecha que permita confiar en él incluso cuando ya ha envejecido. Un documento exhaustivo acaba duplicando el código. Uno que solo contiene lo que el código calla sigue siendo útil años después.
Abre esta semana el último TDD que aprobó tu equipo y busca la sección de alternativas descartadas. Si no existe, o dice "ninguna", ese documento ya está muerto, aunque todavía nadie lo haya notado.
Cada semana analizo un problema real de liderazgo técnico. Con el mismo nivel de profundidad.