116/365 · Vibe coding: cómo documentar decisiones

Hemos hablado de cómo el prompt es diseño instruccional, de cómo estructurar la comunicación con la IA para obtener resultados pedagógicamente sólidos. Pero hay algo que atraviesa todo el proceso de vibe coding y que marca la diferencia entre proyectos que escalan y proyectos que se quedan en el caos: la documentación de decisiones. No me refiero a comentarios técnicos en el código — eso también importa, pero no es lo fundamental. Hablo de documentar por qué tomaste cada decisión de diseño, qué problema intentabas resolver, qué alternativas consideraste, qué funcionó y qué no. Esa documentación es la memoria del proyecto, y sin ella estás condenado a repetir los mismos errores una y otra vez.

Personalmente he aprendido esto de la forma difícil. Cuando empecé a crear herramientas con IA, no documentaba nada. Creaba, iteraba, ajustaba, y seguía adelante. Meses después, cuando quería mejorar una herramienta o crear algo similar, no recordaba por qué había tomado ciertas decisiones. ¿Por qué este botón está aquí y no allí? ¿Por qué esta funcionalidad funciona así y no de otra forma? ¿Qué problema estaba resolviendo con esta estructura? Tenía que reconstruir todo el razonamiento desde cero, perdiendo tiempo valiosísimo. Hasta que entendí: necesito documentar mis decisiones como si se las estuviera explicando a otro docente — o a mi yo futuro, que básicamente es lo mismo.

Y esto conecta directamente con algo que he trabajado extensamente en proyectos como EDUmind y Los Mundos Edufis: la necesidad de que el conocimiento sea transferible, replicable, auditable. Recientemente documenté todo el proceso de creación de estas plataformas en un preprint que cubre desde los primeros conceptos hasta junio de 2025, porque entendí que si esto va a ser útil para otros docentes, necesitan entender no solo QUÉ herramientas creé, sino POR QUÉ las creé así, QUÉ problemas pedagógicos concretos resuelven, CÓMO evolucionaron basándose en uso real. Ese documento es extenso, técnicamente denso en algunos momentos, pero fundamentalmente necesario. Porque sin esa documentación, el proyecto queda como una caja negra — funciona, pero nadie sabe exactamente por qué ni cómo replicarlo o mejorarlo.

Por qué documentar decisiones no es opcional (aunque lo parezca)

Hay una tentación enorme cuando trabajas con vibe coding: pensar que la documentación es algo que harás «después, cuando tenga tiempo». Total, el código está ahí, la herramienta funciona, el alumnado la está usando. ¿Para qué documentar? Pero esa es una trampa. La documentación no es un lujo para cuando sobra tiempo — es parte integral del proceso de desarrollo. Y no solo para otros: principalmente para ti mismo.

Primera razón para documentar: memoria externa de decisiones pedagógicas. Cuando creas una herramienta educativa, cada decisión de diseño tiene una razón pedagógica detrás. Decidiste que el feedback aparezca inmediatamente en lugar de al final porque la investigación sobre evaluación formativa de Dylan Wiliam demuestra que el feedback inmediato es más efectivo. Decidiste limitar las opciones a cuatro en lugar de cinco porque la teoría de carga cognitiva de Sweller indica que reducir opciones disminuye la carga extrínseca. Esas decisiones tienen fundamento. Pero si no las documentas, se pierden. Y cuando seis meses después quieras mejorar la herramienta, no recordarás el razonamiento original.

Segunda razón: facilitar la iteración fundamentada. Documentar decisiones te permite iterar con criterio. Cuando sabes exactamente por qué algo está diseñado de cierta forma, puedes evaluar críticamente si ese razonamiento sigue siendo válido o si nueva evidencia sugiere cambiarlo. Sin documentación, iteras a ciegas — cambias cosas sin saber si estás mejorando o empeorando, porque no tienes registro de la lógica original. He visto esto en mi propia práctica: volver a una herramienta meses después y querer cambiar algo que, si hubiera tenido documentado el razonamiento original, habría entendido que estaba ahí por una razón específica observada con alumnado real.

Tercera razón: transferencia de conocimiento. Si tu herramienta funciona bien y quieres compartirla con otros docentes — que es el espíritu del software libre que defiendo firmemente —, necesitan entender no solo cómo usarla, sino por qué está diseñada así. Esa comprensión les permite adaptarla inteligentemente a sus propios contextos, no solo copiarla mecánicamente. Y la diferencia entre ambas cosas es enorme. Un docente que entiende el razonamiento pedagógico detrás de cada funcionalidad puede modificar la herramienta para su alumnado específico manteniendo la coherencia educativa. Uno que solo tiene el código sin documentación puede romper esa coherencia sin darse cuenta.

Qué documentar: decisiones pedagógicas, técnicas y de iteración

No toda documentación es igual de útil. Documentar por documentar genera ruido. Necesitas documentar selectivamente las decisiones que realmente importan. Y en vibe coding educativo, esas decisiones caen en tres categorías fundamentales.

Primera categoría: decisiones pedagógicas. Estas son las más importantes y las que menos se documentan habitualmente. Incluyen: objetivo de aprendizaje específico que la herramienta apoya, competencias que desarrolla, teorías o investigación educativa en las que se basa el diseño, problemas de aprendizaje concretos que has observado en tu alumnado y que la herramienta intenta resolver, criterios de éxito (cómo sabrás si la herramienta está funcionando pedagógicamente). Por ejemplo, cuando creé EDUmind Quiz, documenté que el diseño se basa en principios de evaluación formativa, que el objetivo no es calificar sino proporcionar feedback para el aprendizaje, que la posibilidad de repetir se fundamenta en investigación sobre práctica espaciada y que permito ver las respuestas correctas después de intentarlo porque la transparencia sobre criterios de éxito es clave según Hattie.

Segunda categoría: decisiones técnicas con implicaciones pedagógicas. No me refiero a documentar cada línea de código — eso va en comentarios dentro del código. Hablo de decisiones técnicas que afectan directamente al uso pedagógico: por qué elegiste que funcione offline (porque muchos centros tienen conectividad limitada), por qué no requiere login (para proteger privacidad del alumnado y reducir barreras de acceso), por qué usaste solo HTML/CSS/JavaScript vanilla (para que cualquier docente con conocimientos básicos pueda auditar y modificar el código), por qué limitaste el tamaño máximo de la aplicación (para que cargue rápido en dispositivos antiguos). Cada una de esas decisiones técnicas tiene un porqué pedagógico o de equidad, y documentarlo ayuda a entender que no son arbitrarias.

Tercera categoría: decisiones de iteración basadas en evidencia. Esta es la documentación más valiosa a largo plazo. Cada vez que pruebas la herramienta con alumnado real y decides cambiar algo basándote en esa evidencia, documéntalo. Qué observaste, qué cambio hiciste, por qué, qué resultado esperabas, qué resultado obtuviste. Esa documentación crea una narrativa de evolución del proyecto que es oro puro para entender cómo mejora una herramienta educativa con el tiempo. Además, esa narrativa puede convertirse en investigación educativa válida — estás documentando ciclos de diseño-implementación-evaluación-rediseño, que es exactamente lo que hacen los investigadores en design-based research.

Formatos útiles de documentación: del README al diario de diseño

Entonces, ¿dónde y cómo documentas? No necesitas sistemas complejos — necesitas formatos simples que realmente uses. Primera opción, la más básica y efectiva: archivo README.md en el repositorio del proyecto. Si usas GitHub o cualquier otro sistema de control de versiones (y deberías), el README es el primer documento que cualquiera ve cuando accede al proyecto. Ahí documenta: qué es la herramienta, para qué sirve pedagógicamente, para quién está diseñada, qué problema resuelve, cómo usarla, cómo modificarla, licencia, créditos, referencias teóricas que fundamentan el diseño.

Segunda opción: diario de decisiones de diseño. Yo mantengo un documento separado para cada proyecto donde voy registrando cronológicamente decisiones importantes. Formato simple: fecha, versión, decisión tomada, razón (problema observado o teoría que la soporta), alternativas consideradas, resultado esperado. Por ejemplo: «15/03/2025 - v1.3 - Decidido añadir opción de modo alto contraste - Razón: dos estudiantes con baja visión reportaron dificultad para distinguir texto en fondos de color - Alternativa considerada: permitir ajuste manual de colores, descartada por complejidad - Resultado esperado: mejorar accesibilidad sin complicar interfaz». Ese registro simple, mantenido consistentemente, se convierte en una fuente riquísima de conocimiento sobre el proyecto.

Tercera opción: documentación embebida en el código mediante comentarios significativos. No me refiero a comentar cada línea — eso es ruido. Hablo de comentarios que explican decisiones no obvias. Si elegiste una estructura de código específica porque facilita que otros docentes modifiquen una parte sin romper otras, documéntalo en un comentario. Si una función está diseñada de forma aparentemente compleja porque resuelve un edge case que observaste con alumnado real, explícalo. Esos comentarios ayudan a mantener la coherencia cuando tú u otros modifiquéis el código más adelante.

Cuarta opción, y esta es más avanzada pero tremendamente valiosa: publicar documentación académica del proceso. No necesita ser un artículo en revista indexada — puede ser un preprint en repositorios como Zenodo, un post detallado en tu blog, una presentación en congresos educativos. Lo importante es hacer público el conocimiento generado: qué funciona, qué no, por qué, con qué evidencia. Eso convierte tu práctica en conocimiento compartido que otros pueden usar, replicar, mejorar. Y contribuye a construir una base de evidencia sobre qué diseños pedagógicos funcionan en contextos reales con vibe coding.

Documentar para compartir: el espíritu del software libre educativo

Hay algo que quiero enfatizar porque conecta directamente con mis valores sobre educación y tecnología: documentar no es solo para ti. Es un acto de generosidad profesional. Cuando creas una herramienta educativa útil y la documentas bien — código, decisiones pedagógicas, proceso de iteración, evidencias de efectividad — estás regalando al mundo no solo una herramienta, sino conocimiento sobre cómo crear herramientas educativas efectivas. Estás bajando la barrera de entrada para otros docentes que quieren hacer lo mismo.

Esto es especialmente importante en el contexto del software libre, que defiendo firmemente. Publicar código con licencia GNU GPL v3 (como hago con todos mis proyectos) garantiza que otros puedan usar, modificar y distribuir libremente. Pero si ese código no está bien documentado, la libertad es más teórica que práctica. Un docente sin formación técnica avanzada puede tener acceso al código pero no saber qué hacer con él si no entiende la lógica detrás. La documentación convierte el acceso formal en acceso real.

También conecta con algo que llevamos viendo en otros posts sobre IA y educación: la necesidad de transparencia. Cuando uso IA para crear herramientas educativas y documento ese proceso — qué prompts usé, cómo iteré, qué funcionó y qué no — estoy haciendo transparente un proceso que muchos mantienen opaco. Y esa transparencia permite que otros aprendan del proceso, no solo del resultado. Es la diferencia entre dar un pez y enseñar a pescar.

Herramientas como EDUmind Motor, EDUmind App o EDUmind Motion tienen valor no solo como aplicaciones funcionales, sino como ejemplos documentados de cómo se pueden crear recursos educativos con vibe coding. Cada una tiene su README explicando objetivos pedagógicos, decisiones de diseño, cómo modificarlas. Y esa documentación es tan importante como el código mismo, porque permite que el conocimiento circule, se replique, se mejore colectivamente.

Si te gusta, nos vemos mañana con la número 117
Luis