El equipo de desarrollo que no documenta bien su arquitectura paga el coste en decisiones repetidas, onboarding lento y deuda de conocimiento. Construye el sistema de documentación técnica que el equipo realmente usa.
Cuándo usarlo: Sistema de documentación técnica para equipos de desarrollo: ADRs, wikis actualizadas y onboarding que funciona.
Herramienta recomendada: Claude
Actúa como un ingeniero de software senior con experiencia construyendo sistemas de documentación de arquitectura que los equipos de desarrollo realmente usan: los Architecture Decision Records que capturan el razonamiento de las decisiones técnicas, las wikis que se mantienen actualizadas, y los materiales de onboarding técnico que llevan a un nuevo developer a ser productivo en semanas en lugar de meses. Necesito mejorar la documentación técnica y de arquitectura de mi equipo. Para asesorarte bien, primero pregúntame: 1. ¿Cuál es el tamaño del equipo de desarrollo y cuál es la complejidad de la arquitectura: monolito, microservicios, serveless, híbrido? 2. ¿Cuál es el mayor problema de conocimiento que tienes: las personas no saben por qué se tomaron ciertas decisiones técnicas, el onboarding de nuevos developers es muy lento, el conocimiento depende de una o dos personas clave, u otro? 3. ¿Qué herramientas de documentación usa ya el equipo: Confluence, Notion, GitHub wiki, docs en el repositorio, o ninguna de forma sistemática? 4. ¿Cuánto tiempo pasan los developers buscando respuestas a preguntas que deberían estar documentadas? 5. ¿Cuál es la velocidad de rotación del equipo y con qué frecuencia se incorporan nuevos developers? Con esas respuestas, diseña el sistema de documentación técnica: **1. Architecture Decision Records: capturar el razonamiento de las decisiones** El ADR es el artefacto de documentación de arquitectura más valioso que existe porque responde la pregunta que más frecuentemente hace un developer que se incorpora al equipo: ¿por qué el sistema está hecho así? Define el sistema de ADRs: el formato del ADR que captura el contexto (cuál era la situación cuando se tomó la decisión), las opciones consideradas con sus trade-offs, la decisión tomada y su justificación, y las consecuencias esperadas, el proceso de creación de ADRs que los integra en el flujo de trabajo de desarrollo (el ADR se escribe antes de implementar la decisión, no después, y se revisa en la code review), la localización de los ADRs en el repositorio (en un directorio /docs/adr numerado cronológicamente para que sean parte del historial del código), y cómo gestionar los ADRs obsoletos cuando la decisión ha cambiado. **2. La wiki técnica que se mantiene actualizada** El cementerio de wikis con información desactualizada es el principal obstáculo para que los developers consulten la documentación existente. Define el sistema de wiki que permanece relevante: el principio de que la documentación debe vivir cerca del código para que el impulso natural de actualizar el código incluya actualizar la documentación, la distinción entre los tipos de documentación con diferentes ciclos de vida (la arquitectura de alto nivel cambia poco, los detalles de implementación cambian con cada release), el proceso de revisión periódica de la wiki (la auditoría semestral que identifica los documentos obsoletos), y la métrica de salud de la wiki que detecta cuando se está dejando de mantener. **3. El onboarding técnico que lleva al developer a ser productivo rápidamente** El coste del onboarding técnico lento es enorme: un developer que tarda tres meses en ser productivo en lugar de tres semanas representa semanas de productividad perdida multiplicadas por el número de incorporaciones al año. Define el sistema de onboarding técnico: el mapa de la arquitectura que da el contexto de alto nivel antes de entrar en los detalles, el diagrama de los componentes principales y sus relaciones que el developer necesita entender antes de tocar código, la guía de setup del entorno de desarrollo local que funciona sin asistencia humana (el test de esta guía es que el developer más nuevo la siga en solitario y registre los problemas), las rutas de onboarding por especialización (el developer de backend y el de frontend necesitan materiales diferentes), y los primeros tickets o tareas guiadas que permiten aprender el codebase contribuyendo desde el primer día. **4. La documentación de los sistemas de producción** Los runbooks, los playbooks de incidencias y la documentación operacional son los documentos más críticos del equipo y los más frecuentemente ignorados hasta que ocurre un incidente. Define la estrategia de documentación operacional: el runbook de cada servicio crítico que describe cómo desplegarlo, escalarlo, diagnosticar sus problemas más comunes y recuperarlo de un fallo, la postmortem como fuente de conocimiento (el postmortem bien escrito que captura el timeline, el análisis de causa raíz y las acciones correctivas se convierte en conocimiento que previene el siguiente incidente), y el proceso de revisión de runbooks antes de cada deploy importante que verifica que la documentación refleja el estado actual del sistema. **5. El proceso de documentación que los developers realmente siguen** El mayor problema de la documentación técnica no es la herramienta ni el formato: es que los developers no documentan porque lo perciben como trabajo adicional que no está en el critical path de la feature. Define la estrategia de integración en el workflow: la definición de hecho (definition of done) que incluye la documentación como criterio de completitud de una feature o un cambio de arquitectura, las plantillas de documentación que reducen el tiempo de escritura al mínimo, la revisión de la documentación como parte del proceso de code review (el revisor verifica que el cambio está documentado si era necesario), y el reconocimiento del trabajo de documentación como contribución de primer nivel igual que el código. **6. Las métricas de salud de la documentación técnica** Define cómo medir si el sistema de documentación funciona: el tiempo medio de onboarding de nuevos developers como indicador primario del valor del sistema (más rápido es mejor), la frecuencia de consulta de los documentos como indicador de relevancia (los documentos que nadie consulta o están mal organizados o no contienen lo que el equipo necesita), el número de preguntas repetidas en Slack o en reuniones que deberían estar respondidas en la documentación (estas son oportunidades de mejora), y la satisfacción del equipo con la documentación medida en la retro periódica. Termina con el plan de implementación para el equipo descrito: las tres iniciativas de mayor impacto en los primeros noventa días y el criterio para saber si el sistema está funcionando.