Una wiki técnica bien estructurada reduce el tiempo de onboarding y evita que el conocimiento se silos en personas concretas. Aprende a diseñar la arquitectura de información, escribir documentación que se mantenga actualizada y crear rituales de mantenimiento. El resultado es un equipo más autónomo y resiliente ante la rotación.
Cuándo usarlo: Diseñar wiki técnica para equipos de desarrollo de software
Herramienta recomendada: Claude
Actúa como ingeniero de software senior con experiencia en gestión del conocimiento y documentación técnica. Ayúdame a diseñar y poner en marcha una wiki técnica para un equipo de desarrollo de entre 5 y 20 personas. **Problema que quiero resolver** El equipo tiene conocimiento valioso disperso: algunos desarrolladores saben cómo está configurado el entorno de producción, otros conocen las decisiones de arquitectura pasadas (ADRs), y los más antiguos recuerdan por qué ciertos patrones se adoptaron. Cuando alguien sale o llega alguien nuevo, hay un cuello de botella enorme. Quiero eliminar ese problema. **Entregables que necesito** 1. **Arquitectura de la wiki**: propón una estructura de carpetas y categorías para organizar el conocimiento técnico. Incluye secciones para: onboarding, arquitectura del sistema, guías de configuración de entornos, runbooks operativos, decisiones de diseño (ADRs), convenciones de código, APIs internas, glosario técnico y postmortems de incidentes. 2. **Plantilla de ADR (Architecture Decision Record)**: crea una plantilla completa con campos para contexto, opciones consideradas, decisión tomada, consecuencias positivas, consecuencias negativas, estado (propuesto / aceptado / obsoleto) y fecha. 3. **Guía para escribir documentación que dure**: lista los principios para escribir documentación técnica que se mantenga útil en el tiempo. Incluye: cómo evitar duplicación, cuándo actualizar vs. archivar, cómo vincular documentos entre sí, y cómo escribir para el lector del futuro que no tiene tu contexto actual. 4. **Runbook de ejemplo**: escribe un runbook completo para un escenario ficticio: reiniciar un worker de colas en producción cuando está bloqueado. Incluye síntomas, pasos de diagnóstico, comandos exactos, verificación de solución y escalado si no funciona. 5. **Ritual de mantenimiento**: propón un proceso ligero para mantener la wiki actualizada. Define quién es responsable de cada sección, con qué frecuencia se revisa, cómo detectar documentación obsoleta, y cómo incorporar el hábito de documentar en el flujo de trabajo diario (por ejemplo, al cerrar un ticket o desplegar un cambio significativo). 6. **Métricas de salud de la wiki**: define 3-5 indicadores para saber si la wiki está siendo útil (por ejemplo, número de búsquedas sin resultado, tiempo medio de onboarding, número de páginas sin editar en más de 6 meses). **Formato de salida** Devuelve cada entregable con su propio encabezado. Usa bloques de código para comandos y plantillas. Sé específico y práctico; evita respuestas genéricas que no se puedan aplicar directamente.